PolarDB-X Cloud Zero MCP Server

Give any AI agent persistent MySQL databases through the Model Context Protocol.

Supports multiple simultaneous instances — create, manage, and query several databases at once.

How It Works

┌──────────────┐       MCP (stdio/http)       ┌──────────────────┐
│   AI Agent   │  ◄──────────────────────────► │  MCP Server      │
│ (Qoder, etc) │                               │  (this project)  │
└──────────────┘                               └────────┬─────────┘
                                                        │
                                     MySQL protocol     │  Zero API (HTTP)
                                     (pymysql + SSL)    │  (on-demand creation)
                                                        │
                                               ┌────────▼─────────┐
                                               │  PolarDB-X Cloud │
                                               │      Zero        │
                                               └──────────────────┘

1. Agent calls create_instance() to create one or more databases (or provide credentials via env vars)
2. Server registers instances in a local registry (~/.polardbx-zero-mcp/instances.json)
3. All tools require an explicit instance_id — use list_instances() to discover them
4. SQL is executed over the MySQL wire protocol (pymysql + SSL)

Installation

pip install polardbx-zero-mcp

IDE / MCP Client Configuration

Claude Code:

claude mcp add polardbx -- polardbx-zero-mcp

Qoder / Cursor / Windsurf / Claude Desktop — add to mcp.json:

{
  "mcpServers": {
    "polardbx": {
      "command": "polardbx-zero-mcp"
    }
  }
}

From source

git clone https://github.com/polardb/polardbx-zero-mcp.git
cd polardbx-zero-mcp
pip install -e .
polardbx-zero-mcp

HTTP transport: polardbx-zero-mcp --transport http (default http://localhost:8000/mcp)

Configuration

By default, no configuration is needed — just call create_instance() to get a free database.

To connect to your own MySQL or PolarDB-X instance, pass credentials via env. They will be registered as instance_id="env":

{
  "mcpServers": {
    "polardbx": {
      "command": "polardbx-zero-mcp",
      "env": {
        "MYSQL_URL": "mysql://user:password@host:3306/mydb"
      }
    }
  }
}

Or use individual variables:

Tools

Instance Management

SQL Execution

All SQL tools require instance_id. Use execute_sql_tool for any SQL including SHOW TABLES, DESCRIBE, SHOW DATABASES, etc.

Stateful Connections

Connections are bound to a specific instance. The conn_id includes the instance name (e.g. db1_conn_1) for easy identification.

Key Parameters

create_instance:

execute_sql_tool:

batch_execute:

acquire_connection:

Development

pip install -e .                     # Install in editable mode
mcp dev polardbx_zero_mcp.py          # Test with MCP Inspector
polardbx-zero-mcp --transport http   # Run HTTP server

License

Apache-2.0