mcp -tidb

This MCP server provides a TiDB-compatible interface for a TiDB Cloud (serverless) database. It reads connection details from environment variables (or a .env file) and exposes a SQL interface that clients can connect to using the TiDB protocol. To run it, start the server with uv as shown in the installation guide, ensuring that TIDB_HOST, TIDB_PORT, TIDB_USERNAME, TIDB_PASSWORD, and TIDB_DATABASE are set to your TiDB instance credentials. Once running, you can connect your SQL client or application to the TiDB host and port and execute standard SQL queries against your TiDB Cloud cluster through this MCP server.

If you’re configuring via Claude Desktop, you can point Claude at the local mcp server using the provided config. The config in Claude Desktop specifies a command to invoke uv with the working directory and runs src/main.py, effectively starting the MCP server within your environment. This makes it easy to automate startup as part of Claude workflows or scripts.

For WSL users, you can wrap the uv invocation in a shell command within claude_desktop_config.json as shown in the README, ensuring the correct path mappings between Windows and Linux filesystems. The TiDB connection details (host, port, credentials, database) remain the same, but the command invocation ensures the server starts in the appropriate environment.

Prerequisites:

• Python (via uv) - uv is the Python package installer for the MCP server.

Install steps:

1. Clone the repository

   git clone https://github.com/c4pt0r/mcp-server-tidb
   cd mcp-server-tidb
   

2. Install the package and dependencies using uv

   uv venv
   uv pip install -e .
   

3. Configure environment variables (examples):

   export TIDB_HOST=gateway01.us-east-1.prod.aws.tidbcloud.com
   export TIDB_PORT=4000
   export TIDB_USERNAME=your-username
   export TIDB_PASSWORD=your-password
   export TIDB_DATABASE=test
   

4. Run the server (example):

   uv run src/main.py
   

Note: If you prefer using Claude Desktop, follow the provided Claude Desktop config example to connect from Claude to your local MCP server.

Tips and common issues:

• Ensure your TiDB credentials and host are correct; a misconfigured host/port will prevent connections.
• If you’re using a local environment with WSL, consider using the provided claude_desktop_config.json snippet to wrap the uv invocation properly for Windows/WSL interoperability.
• The default TiDB port is 4000 if TIDB_PORT is not set; override as needed.
• When running in serverless TiDB Cloud, network access from the MCP server to the TiDB cluster must be allowed (security groups, VPC peering, etc.).
• Keep your Python environment isolated (venv) to avoid dependency conflicts with other projects.
• If you encounter connection timeouts, verify that TIDB_HOST resolves from the host where the MCP server is running and that there are no firewall rules blocking port 4000.