📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

Connect AI Tools to TiDB Cloud Lake Using MCP

The TiDB Cloud Lake MCP server connects AI assistants to TiDB Cloud Lake through the Model Context Protocol (MCP). With an MCP-compatible tool, you can explore database objects, inspect table schemas, and run SQL using natural-language instructions.

Prerequisites

Before you begin, make sure that you have the following:

  • Python 3.12 or later
  • uv installed
  • An MCP-compatible AI tool
  • A TiDB Cloud Lake account, database, and warehouse

Get a connection string

Get the host, username, password, database, and warehouse name from your TiDB Cloud Lake warehouse. For more information, see Connect to a Warehouse.

Build a DSN using the following format:

lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>

Configure an MCP client

The following configurations run the latest tidbcloudlake-mcp package with uv. Safe mode is enabled explicitly in each example.

    codex mcp add lake-mcp \
    --env LAKE_DSN='lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>' \
    --env LAKE_MCP_SAFE_MODE=true \
    -- uv tool run --from tidbcloudlake-mcp@latest lake-mcp

    claude mcp add lake-mcp \
    --env LAKE_DSN='lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>' \
    --env LAKE_MCP_SAFE_MODE=true \
    -- uv tool run --from tidbcloudlake-mcp@latest lake-mcp

    Add the following server to your Cursor MCP configuration:

    {
  "mcpServers": {
    "lake-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--from", "tidbcloudlake-mcp@latest", "lake-mcp"],
      "env": {
        "LAKE_DSN": "lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>",
        "LAKE_MCP_SAFE_MODE": "true"
      }
    }
  }
}

    Add the following server to the mcpServers object in your Gemini CLI settings.json file:

    {
  "mcpServers": {
    "lake-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--from", "tidbcloudlake-mcp@latest", "lake-mcp"],
      "env": {
        "LAKE_DSN": "lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>",
        "LAKE_MCP_SAFE_MODE": "true"
      }
    }
  }
}

    For an MCP client that accepts the standard JSON configuration, add the following server:

    {
  "mcpServers": {
    "lake-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--from", "tidbcloudlake-mcp@latest", "lake-mcp"],
      "env": {
        "LAKE_DSN": "lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>",
        "LAKE_MCP_SAFE_MODE": "true"
      }
    }
  }
}

    Restart the AI tool after saving its MCP configuration. You can then ask the tool to list databases, inspect tables, or run a query.

    Session sandbox protection

    LAKE_MCP_SAFE_MODE controls whether the server validates write operations against a session-specific sandbox.

    ValueBehavior
    trueProduction objects are read-only for the AI tool. Writes are limited to objects whose names start with the current mcp_sandbox_{session_id}_* prefix. This is the default and recommended setting.
    falseThe server allows any SQL operation permitted by the configured TiDB Cloud Lake user. Use this setting only with a trusted tool and a least-privilege account.

    The MCP tool get_session_sandbox_prefix returns the prefix for the current session.

    For server transports, configuration variables, and the available MCP tools, see TiDB Cloud Lake MCP Server.

    Was this page helpful?