MCPgee
MCPgee
MCPgeeMCPgee

TiDB

v1.0.0•Databases•stable

mcp server for tidb

tidbmcpai-integration
Share:
23
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is TiDB?

TiDB is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server for tidb

mcp server for tidb

This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • mcp server for tidb

Use Cases

Query and manage TiDB database through MCP.
Perform analytics and data operations without writing SQL directly.
c4pt0r

Maintainer

LicenseApache-2.0
Languagepython
Versionv1.0.0
UpdatedJan 9, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx tidb

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use TiDB

The TiDB MCP server connects AI assistants directly to a TiDB Serverless database, enabling natural language queries, schema inspection, and data operations without requiring users to write SQL manually. It reads connection details from environment variables and exposes the database through the MCP protocol so that clients like Claude Desktop can execute queries, explore table structures, and perform analytics on TiDB's MySQL-compatible, horizontally scalable cloud database. It is designed for developers and data engineers who want to interact with their TiDB Serverless clusters using conversational AI.

Prerequisites

  • A TiDB Serverless account and cluster at tidbcloud.com
  • TiDB connection credentials: host, port (4000), username, password, and database name
  • Python and uv package manager installed
  • An MCP-compatible client such as Claude Desktop
1

Create a TiDB Serverless cluster

Sign up at tidbcloud.com and create a free TiDB Serverless cluster. Note your connection host, username, password, and database name from the cluster connection page.

2

Clone and install the MCP server

Clone the repository and install it in a uv virtual environment.

git clone https://github.com/c4pt0r/mcp-server-tidb
cd mcp-server-tidb
uv venv
uv pip install -e .
3

Set your TiDB connection environment variables

Configure the required environment variables with your TiDB Serverless connection details.

export TIDB_HOST=gateway01.us-east-1.prod.aws.tidbcloud.com
export TIDB_PORT=4000
export TIDB_USERNAME=xxxxxxxxxx.your_username
export TIDB_PASSWORD=your_password
export TIDB_DATABASE=test
4

Add the server to Claude Desktop config

Edit your Claude Desktop configuration file to register the TiDB MCP server. Replace /path/to/mcp-server-tidb with your actual clone location.

{
  "mcpServers": {
    "tidb": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-tidb", "run", "src/main.py"],
      "env": {
        "TIDB_HOST": "gateway01.us-east-1.prod.aws.tidbcloud.com",
        "TIDB_PORT": "4000",
        "TIDB_USERNAME": "xxxxxxxxxx.your_username",
        "TIDB_PASSWORD": "your_password",
        "TIDB_DATABASE": "test"
      }
    }
  }
}
5

Restart Claude Desktop and verify connection

Quit and reopen Claude Desktop. The TiDB server should appear as connected. Ask Claude to list your tables to verify.

TiDB Examples

Client configuration

Full Claude Desktop configuration with all required TiDB connection environment variables inline.

{
  "mcpServers": {
    "tidb": {
      "command": "uv",
      "args": ["--directory", "/Users/yourname/mcp-server-tidb", "run", "src/main.py"],
      "env": {
        "TIDB_HOST": "gateway01.us-east-1.prod.aws.tidbcloud.com",
        "TIDB_PORT": "4000",
        "TIDB_USERNAME": "your_prefix.your_username",
        "TIDB_PASSWORD": "your_password",
        "TIDB_DATABASE": "test"
      }
    }
  }
}

Prompts to try

Natural language database interactions once TiDB MCP is connected to Claude.

- "List all tables in my TiDB database"
- "Show me the schema of the orders table"
- "How many rows are in the users table?"
- "Find the top 10 customers by total order value in the last 30 days"
- "Create a new table called events with columns id, name, created_at"
- "What indexes exist on the products table?"

Troubleshooting TiDB

Connection refused or timeout when connecting to TiDB

Verify TIDB_HOST and TIDB_PORT are correct and that your TiDB Serverless cluster is active. TiDB Serverless clusters have an inactivity timeout — open the TiDB Cloud console to wake the cluster if it was paused.

Authentication fails with 'Access denied' error

TiDB Serverless usernames include a cluster prefix in the format `prefix.username` (e.g. `3abc1234.root`). Copy the exact username string from the TiDB Cloud connection string rather than entering just the base username.

WSL users see 'command not found: uv' in Claude Desktop

When running under WSL, update your Claude Desktop config to use wsl.exe as the command: `"command": "wsl.exe"` with args `["bash", "-c", "/home/user/.local/bin/uv --directory /path/to/mcp-server-tidb run python src/main.py"]`.

Frequently Asked Questions about TiDB

What is TiDB?

TiDB is a Model Context Protocol (MCP) server that mcp server for tidb It connects AI assistants to external tools and data sources through a standardized interface.

How do I install TiDB?

Follow the installation instructions on the TiDB GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with TiDB?

TiDB works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is TiDB free to use?

Yes, TiDB is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

TiDB Alternatives — Similar Databases Servers

Looking for alternatives to TiDB? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.

Excelize

★ 20.6k

Go language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets

MCP Toolbox for Databases

★ 15.3k

Open source MCP server specializing in easy, fast, and secure tools for Databases.

DBHub

★ 2.8k

A universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.

Tabularis

★ 2.1k

A lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.

Postgres AI Guide

★ 1.7k

MCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.

Anyquery

★ 1.7k

🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.

Browse More Databases MCP Servers

Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

DatabasesBrowse All Servers

Quick Config Preview

{ "mcpServers": { "tidb": { "command": "npx", "args": ["-y", "tidb"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use TiDB?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides