home / mcp / tidb mcp server

TiDB MCP Server

Provides a TiDB MCP server that connects to a serverless TiDB Cloud cluster for MCP clients to query and manage data.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "c4pt0r-mcp-server-tidb": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-tidb",
        "run",
        "src/main.py"
      ],
      "env": {
        "TIDB_HOST": "YOUR_TIDB_HOST",
        "TIDB_PORT": "YOUR_TIDB_PORT",
        "TIDB_DATABASE": "YOUR_TIDB_DATABASE",
        "TIDB_PASSWORD": "YOUR_TIDB_PASSWORD",
        "TIDB_USERNAME": "YOUR_TIDB_USERNAME"
      }
    }
  }
}

You can run a TiDB MCP server locally or in WSL to access a serverless TiDB database cluster. This MCP server acts as a bridge that lets your MCP clients query and interact with TiDB without managing the database directly. It supports running via uv in a dedicated directory and can be configured with environment variables for your TiDB connection details.

How to use

You interact with the TiDB MCP server through your MCP client by pointing the client to the server via the standard MCP workflow. Start the server in your environment, then configure your client to connect using the host, port, database name, and credentials you provide. Typically you will supply the TiDB host, port, username, password, and database name. Once started, you can run queries, manage data, and perform operations supported by the TiDB MCP server through your MCP client as if you were talking directly to TiDB.

How to install

Prerequisites you need before installation:

Python and a Python package installer are available on your system
Git is installed to clone repositories (or you can download the source as a folder)

Concrete steps to install the TiDB MCP server locally:

# Clone the TiDB MCP server repository
git clone https://github.com/c4pt0r/mcp-server-tidb
cd mcp-server-tidb

# Create a virtual environment and activate it using the uv tool
uv venv

# Install the package and dependencies
uv pip install -e .

Additional sections

Configuration details you will need to connect to TiDB Cloud TiDB (serverless): you set up a TiDB cluster on tidbcloud.com and then provide the connection details to the MCP server via environment variables. The following environment variables are supported for the TiDB MCP server:

- TIDB_HOST - TiDB host address, for example gateway01.us-east-1.prod.aws.tidbcloud.com.

- TIDB_PORT - TiDB port (default: 4000).

- TIDB_USERNAME - Database username, e.g. xxxxxxxxxx.<username>.

- TIDB_PASSWORD - Database password.

- TIDB_DATABASE - Database name, default is test.

You can provide these variables through your environment or by placing them in a .env file in your working directory.

When you are integrating with Claude Desktop, you can configure the MCP server to run through a dedicated command that launches the MCP server in the correct directory. The following example shows how to configure Claude Desktop to run the server from a specified directory and start the main script.

{
  "mcpServers": {
      "tidb": {
          "command": "uv",
          "args": [
              "--directory",
              "/path/to/mcp-server-tidb",
              "run",
              "src/main.py"
          ]
      }
  }
}

WSL run configuration

If you are running mcp-server-tidb in Windows Subsystem for Linux (WSL), use the following configuration to start the server from within WSL via Claude Desktop.

{
  "mcpServers": {
    "tool-with-env-vars": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "/path/to/uv --directory /path/to/mcp-server-tidb run python src/main.py"
      ]
    }
  }
}

Available tools

QueryTiDB

Executes SQL queries against the TiDB database through the MCP server, returning results to the MCP client.

ListTables

Lists tables in the connected TiDB database to help clients discover schema.