Yes. The TiDB MCP Server is open source as part of PingCAP's PyTiDB SDK and free to run. You only pay for whatever TiDB cluster or TiDB Cloud service it connects to.

Does it support remote/OAuth?

The primary distribution is a local stdio server launched with uvx that authenticates with host, port, user, password, and database env vars. An optional SSE transport mode is available for HTTP clients, but there is no hosted OAuth endpoint.

Is TiDB compatible with MySQL?

Yes. TiDB speaks the MySQL protocol, so the server's query and execute tools work with standard MySQL-style SQL against a distributed, HTAP-capable database.

TiDB MCP server

OfficialPingCAP31Config last verified Jun 1, 2026

PingCAP's official MCP server lets agents explore databases and run SQL against TiDB, the MySQL-compatible distributed SQL database.

The TiDB MCP Server is PingCAP's official integration that connects a coding agent to TiDB, the open-source, MySQL-compatible distributed SQL database with native support for transactions, analytics, and vector search. It ships as part of PyTiDB, PingCAP's AI SDK for TiDB, and gives an agent the tools it needs to navigate a cluster: list the databases, switch into one, list the tables inside it, and then run SQL. Because TiDB speaks the MySQL protocol, the same workflow an agent knows from MySQL applies directly here, but against a horizontally scalable, HTAP-capable backend.

The server separates reads from writes at the tool level: db_query runs read-only SQL while db_execute runs data-modification statements, so an agent's intent is explicit and you can reason about what it is allowed to do. It also exposes lightweight user management with db_create_user and db_remove_user. It runs locally over stdio, launched with uvx from the pytidb package with the mcp extra, and authenticates with TIDB_HOST, TIDB_PORT, TIDB_USERNAME, TIDB_PASSWORD, and TIDB_DATABASE environment variables, working against both self-managed TiDB and TiDB Cloud. An optional SSE transport mode is available for HTTP-based clients.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "tidb": {
      "command": "uvx",
      "args": [
        "--from",
        "pytidb[mcp]",
        "tidb-mcp-server"
      ],
      "env": {
        "TIDB_HOST": "<TIDB_HOST>",
        "TIDB_PORT": "<TIDB_PORT>",
        "TIDB_USERNAME": "<TIDB_USERNAME>",
        "TIDB_PASSWORD": "<TIDB_PASSWORD>",
        "TIDB_DATABASE": "<TIDB_DATABASE>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add tidb -- uvx --from pytidb[mcp] tidb-mcp-server

Step-by-step guides

Available tools

Tool	Description
show_databases	Lists all databases available in the connected TiDB cluster.
switch_database	Switches the active connection to a specified database.
show_tables	Lists all tables in the current database.
db_query	Executes a read-only SQL query against TiDB and returns the result set.
db_execute	Executes data-modification SQL statements (INSERT, UPDATE, DELETE, DDL) against TiDB.
db_create_user	Creates a new database user in TiDB.
db_remove_user	Removes an existing database user from TiDB.

Required configuration

TIDB_HOSTRequired
Hostname of your TiDB server or TiDB Cloud cluster.
TIDB_PORTRequired
Port of the TiDB server, typically 4000.
TIDB_USERNAMERequired
TiDB username used to authenticate.
TIDB_PASSWORDRequired
Password for the TiDB user.
TIDB_DATABASERequired
Default database to connect to.

What you can do with it

Query a TiDB cluster in natural language

Let an agent call show_databases and show_tables to learn the schema, then run db_query to answer analytics or operational questions against a MySQL-compatible distributed SQL backend.

Apply controlled changes to data

Use db_execute for explicit data modifications and db_create_user / db_remove_user for lightweight access management, keeping reads and writes separated at the tool level.

FAQ

Is it free?: Yes. The TiDB MCP Server is open source as part of PingCAP's PyTiDB SDK and free to run. You only pay for whatever TiDB cluster or TiDB Cloud service it connects to.
Does it support remote/OAuth?: The primary distribution is a local stdio server launched with uvx that authenticates with host, port, user, password, and database env vars. An optional SSE transport mode is available for HTTP clients, but there is no hosted OAuth endpoint.
Is TiDB compatible with MySQL?: Yes. TiDB speaks the MySQL protocol, so the server's query and execute tools work with standard MySQL-style SQL against a distributed, HTAP-capable database.

← Browse all databases servers