Name: TiDB
Author: c4pt0r

LABSCO SUMMARY

The shortest path from a free TiDB cluster to an assistant that can see it.

There is no package to install and no account beyond TiDB Cloud: clone, create the venv, paste five environment variables. The README's Windows guidance is worth reading if you run under WSL, where the client has to invoke wsl.exe rather than uv directly.

What it is

A small MCP server for TiDB Serverless. It connects to a single cluster chosen at launch, so the assistant works against one database rather than being handed a connection string per request.

What you get

A connection to one TiDB Serverless cluster, addressed by host and port — for example gateway01.us-east-1.prod.aws.tidbcloud.com on port 4000
The database is pinned by TIDB_DATABASE, which defaults to test, so a session cannot wander into a neighbouring schema
Configuration comes from environment variables or a .env file, which keeps the credentials out of the client config if you prefer

Requirements

A checkout of the repository and uv — installed with uv venv and uv pip install -e ., then launched as uv --directory <YOUR_PATH_TO_MCP_SERVER_TIDB> run src/main.py. It needs TIDB_HOST, TIDB_PORT, TIDB_USERNAME, TIDB_PASSWORD and TIDB_DATABASE; a free cluster can be created at tidbcloud.com.

Setup effort

Build from source — git clone https://github.com/c4pt0r/mcp-server-tidb

See installation options

USE CASES

01

Asking questions about data that lives in TiDB

The cluster is already selected, so a question does not start with pasting a connection string.

02

Keeping a session inside one database

TIDB_DATABASE fixes the schema at launch rather than per call.

03

Running it from a Windows client

The README gives the WSL form of the launch command, which is the part that usually breaks.

BEFORE YOU INSTALL

What to know first

Requires

uv
A TiDB Serverless cluster (free at tidbcloud.com)
TIDB_HOST, TIDB_PORT, TIDB_USERNAME, TIDB_PASSWORD and TIDB_DATABASE, all set

Where it runs

Both documented setups run the server on your machine.

INSTALLATION

Connect your client

Server setup

TERMINAL

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

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

MCP Clients

Claude Desktop

CLAUDE DESKTOP · JSON

{
  "mcpServers": {
    "tidb": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_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": "<YOUR_TIDB_USERNAME>.<YOUR_USERNAME>",
        "TIDB_PASSWORD": "<YOUR_TIDB_PASSWORD>",
        "TIDB_DATABASE": "test"
      }
    }
  }
}

<YOUR_PATH_TO_MCP_SERVER_TIDB> is the absolute path to your clone, and the TIDB_* values are your cluster's host, port, username, password and database. All five must be set, or the server stops with "Missing environment variables".

Claude Desktop — WSL

CLAUDE DESKTOP — WSL · JSON

{
  "mcpServers": {
    "tool-with-env-vars": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "<YOUR_PATH_TO_UV> --directory <YOUR_PATH_TO_MCP_SERVER_TIDB> run python src/main.py"
      ]
    }
  }
}

<YOUR_PATH_TO_UV> is the full path of uv and <YOUR_PATH_TO_MCP_SERVER_TIDB> the full path of your clone, both as WSL sees them. Put the five TIDB_* values in a .env file in your clone (copy .env.example); the server reads it at startup.

TiDB