Get Started with Cursor and TiDB MCP Server

This guide shows how to configure the TiDB MCP Server in the Cursor editor.

For one-click installation, click the following button:

Prerequisites

Before you begin, ensure you have the following:

• Cursor: Download and install Cursor from cursor.com.
• Python (>=3.10) and uv: Ensure Python (3.10 or later) and uv are installed. Follow the installation guide to install uv.
• A TiDB Cloud Starter instance: You can create a free TiDB Cloud Starter instance on TiDB Cloud.

Connect to TiDB Cloud Starter (recommended)

Use the TiDB Cloud console to create a Cursor configuration with your TiDB Cloud Starter instance credentials.

1. On the My TiDB page, click the name of your target TiDB Cloud Starter instance to go to its overview page, and then click Use with AI Tools in the upper-right corner.

2. In the displayed dialog, select the Branch and Database that Cursor should access.

3. Review the Prerequisites list in the dialog and install any missing dependencies.

4. Configure the root password:

   • If you have not set a password yet, click Generate Password and store it in a secure location (it is shown only once).
   • If a password already exists, enter it in the Enter the password for easy setup field.
   • If you forget the password, click Reset password in the Prerequisites section to generate a new one.

5. Select the Cursor tab, click Add to Cursor, and then click Install in Cursor.

Manual configuration (any TiDB cluster)

If you prefer manual setup, add the following configuration to your .cursor/mcp.json file and replace the placeholders with your connection parameters:

{
  "mcpServers": {
    "TiDB": {
      "command": "uvx --from pytidb[mcp] tidb-mcp-server",
      "env": {
        "TIDB_HOST": "<YOUR_TIDB_HOST>",
        "TIDB_PORT": "<YOUR_TIDB_PORT>",
        "TIDB_USERNAME": "<YOUR_TIDB_USERNAME>",
        "TIDB_PASSWORD": "<YOUR_TIDB_PASSWORD>",
        "TIDB_DATABASE": "<YOUR_TIDB_DATABASE>"
      }
    }
  }
}

For more details, see the Model Context Protocol documentation.

Troubleshooting

If you encounter issues installing the TiDB MCP Server, check the MCP logs in Cursor.

1. Click View > Output in the main menu at the top of the editor.
2. Select MCP from the dropdown menu in the Output panel.
3. If you see errors like [error] Could not start MCP server tidb-mcp-server: Error: spawn uvx ENOENT, it means the uvx command might not exist in your system $PATH environment variable. For macOS users, you can install uvx by running brew install uv.