AnalyticDB for MySQL MCP Server

English | 中文

AnalyticDB for MySQL MCP Server is a universal interface between AI Agents and AnalyticDB MySQL. It provides two categories of capabilities:

• OpenAPI Tools (openapi group): Manage clusters, whitelists, accounts, networking, monitoring, diagnostics, and audit logs via Alibaba Cloud OpenAPI.
• SQL Tools & Resources (sql group): Connect directly to ADB MySQL clusters to execute SQL, view execution plans, and browse database metadata.

Read-only tools are annotated with ToolAnnotations(readOnlyHint=True) per the MCP protocol, allowing clients to distinguish them from mutating operations.

一、Prerequisites

• Python >= 3.13
• uv (recommended package manager and runner)
• Alibaba Cloud AccessKey (required for OpenAPI tools)
• Optional: ADB MySQL connection credentials (for SQL tools in direct-connection mode)

二、Quick Start

2.1 Using cherry-studio (Recommended)

1. Download and install cherry-studio
2. Follow the documentation to install uv, which is required for the MCP environment
3. Configure and use ADB MySQL MCP according to the documentation. You can quickly import the configuration using the JSON below.

Configuration A — SQL tools only (execute queries, view plans, browse metadata):

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "name": "adb-mysql-mcp-server",
      "type": "stdio",
      "isActive": true,
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alibabacloud-adb-mysql-mcp-server",
        "run",
        "adb-mysql-mcp-server"
      ],
      "env": {
        "ADB_MYSQL_HOST": "your_adb_mysql_host",
        "ADB_MYSQL_PORT": "3306",
        "ADB_MYSQL_USER": "your_username",
        "ADB_MYSQL_PASSWORD": "your_password",
        "ADB_MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Configuration B — OpenAPI tools (cluster management, diagnostics, monitoring):

Note: Please set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET to your Alibaba Cloud AccessKey credentials.

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "name": "adb-mysql-mcp-server",
      "type": "stdio",
      "isActive": true,
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alibabacloud-adb-mysql-mcp-server",
        "run",
        "adb-mysql-mcp-server"
      ],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "your_access_key_id",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "your_access_key_secret"
      }
    }
  }
}

You can combine both configurations by setting all environment variables together. When AK/SK is not configured, OpenAPI tools are automatically disabled — only SQL tools remain active.

2.2 Using Claude Code

Download from GitHub and sync dependencies:

git clone https://github.com/aliyun/alibabacloud-adb-mysql-mcp-server
cd alibabacloud-adb-mysql-mcp-server
uv sync

Add the following configuration to the Claude Code MCP config file (project-level: .mcp.json in the project root, or user-level: ~/.claude/settings.json):

stdio transport:

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alibabacloud-adb-mysql-mcp-server",
        "run",
        "adb-mysql-mcp-server"
      ],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "your_access_key_id",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "your_access_key_secret",
        "ALIBABA_CLOUD_SECURITY_TOKEN": "",
        // Uncomment the following lines to enable SQL tools for direct database connection:
        // "ADB_MYSQL_HOST": "your_adb_mysql_host",
        // "ADB_MYSQL_PORT": "3306",
        // "ADB_MYSQL_USER": "your_username",
        // "ADB_MYSQL_PASSWORD": "your_password",
        // "ADB_MYSQL_DATABASE": "your_database"
      }
    }
  }
}

SSE transport — start the server first, then configure the client:

export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# Uncomment the following lines to enable SQL tools for direct database connection:
# export ADB_MYSQL_HOST="your_adb_mysql_host"
# export ADB_MYSQL_PORT="3306"
# export ADB_MYSQL_USER="your_username"
# export ADB_MYSQL_PASSWORD="your_password"
# export ADB_MYSQL_DATABASE="your_database"
export SERVER_TRANSPORT=sse
export SERVER_PORT=8000

uv --directory /path/to/alibabacloud-adb-mysql-mcp-server run adb-mysql-mcp-server

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Streamable HTTP transport — start the server first, then configure the client:

export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# Uncomment the following lines to enable SQL tools for direct database connection:
# export ADB_MYSQL_HOST="your_adb_mysql_host"
# export ADB_MYSQL_PORT="3306"
# export ADB_MYSQL_USER="your_username"
# export ADB_MYSQL_PASSWORD="your_password"
# export ADB_MYSQL_DATABASE="your_database"
export SERVER_TRANSPORT=streamable_http
export SERVER_PORT=8000

uv --directory /path/to/alibabacloud-adb-mysql-mcp-server run adb-mysql-mcp-server

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Note: When ADB_MYSQL_USER and ADB_MYSQL_PASSWORD are not configured but AK/SK is available, a temporary database account is automatically created via OpenAPI for SQL execution and cleaned up afterward.

2.3 Using Cline

Set environment variables and run the MCP server:

export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
export SERVER_TRANSPORT=sse
export SERVER_PORT=8000

uv --directory /path/to/alibabacloud-adb-mysql-mcp-server run adb-mysql-mcp-server

Then configure the Cline remote server:

remote_server = "http://127.0.0.1:8000/sse"

三、Environment Variables

Variable	Required	Description
ALIBABA_CLOUD_ACCESS_KEY_ID	Yes (OpenAPI tools)	Alibaba Cloud AccessKey ID
ALIBABA_CLOUD_ACCESS_KEY_SECRET	Yes (OpenAPI tools)	Alibaba Cloud AccessKey Secret
ALIBABA_CLOUD_SECURITY_TOKEN	No	STS temporary security token
ADB_MYSQL_HOST	No	Database host (direct-connection mode)
ADB_MYSQL_PORT	No	Database port, default 3306 (direct-connection mode)
ADB_MYSQL_USER	No	Database username (direct-connection mode)
ADB_MYSQL_PASSWORD	No	Database password (direct-connection mode)
ADB_MYSQL_DATABASE	No	Default database name (direct-connection mode)
ADB_MYSQL_CONNECT_TIMEOUT	No	Database connection timeout in seconds, default 2
ADB_API_CONNECT_TIMEOUT	No	OpenAPI connection timeout in milliseconds, default 10000 (10s)
ADB_API_READ_TIMEOUT	No	OpenAPI read timeout in milliseconds, default 300000 (5min)
SERVER_TRANSPORT	No	Transport protocol: stdio (default), sse, streamable_http
SERVER_PORT	No	SSE/HTTP server port, default 8000

四、Tool List

4.1 Cluster Management (group: openapi)

Tool	Description
describe_db_clusters	List ADB MySQL clusters in a region
describe_db_cluster_attribute	Get detailed cluster attributes
describe_cluster_access_whitelist	Get cluster IP whitelist
modify_cluster_access_whitelist	Modify cluster IP whitelist
describe_accounts	List database accounts in a cluster
describe_cluster_net_info	Get cluster network connection info
get_current_time	Get current server time

4.2 Diagnostics & Monitoring (group: openapi)

Tool	Description
describe_db_cluster_performance	Query cluster performance metrics (CPU, memory, QPS, etc.)
describe_db_cluster_health_status	Query cluster health status
describe_diagnosis_records	Query SQL diagnosis summary records
describe_diagnosis_sql_info	Get SQL execution details (plan, runtime info)
describe_bad_sql_detection	Detect bad SQL impacting cluster stability
describe_sql_patterns	Query SQL pattern list
describe_table_statistics	Query table-level statistics

4.3 Administration & Audit (group: openapi)

Tool	Description
create_account	Create a database account
modify_db_cluster_description	Modify cluster description
describe_db_cluster_space_summary	Get cluster storage space summary
describe_audit_log_records	Query SQL audit log records

4.4 Advanced Diagnostics (group: openapi)

Tool	Description
describe_executor_detection	Compute node diagnostics
describe_worker_detection	Storage node diagnostics
describe_controller_detection	Access node diagnostics
describe_available_advices	Get optimization advices
kill_process	Kill a running query process
describe_db_resource_group	Get resource group configuration
describe_excessive_primary_keys	Detect tables with excessive primary keys
describe_oversize_non_partition_table_infos	Detect oversized non-partition tables
describe_table_partition_diagnose	Diagnose table partitioning issues
describe_inclined_tables	Detect data-skewed tables

4.5 SQL Tools (group: sql)

Tool	Description
execute_sql	Execute SQL on an ADB MySQL cluster
get_query_plan	Get EXPLAIN execution plan
get_execution_plan	Get EXPLAIN ANALYZE actual execution plan

4.6 MCP Resources (group: sql)

Resource URI	Description
adbmysql:///databases	List all databases
adbmysql:///{database}/tables	List all tables in a database
adbmysql:///{database}/{table}/ddl	Get table DDL
adbmysql:///config/{key}/value	Get a config key value

五、Local Development

git clone https://github.com/aliyun/alibabacloud-adb-mysql-mcp-server
cd alibabacloud-adb-mysql-mcp-server
uv sync

Run tests:

uv run python -m pytest test/ -v

Debug with MCP Inspector:

npx @modelcontextprotocol/inspector \
  -e ALIBABA_CLOUD_ACCESS_KEY_ID=your_ak \
  -e ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_sk \
  uv --directory /path/to/alibabacloud-adb-mysql-mcp-server run adb-mysql-mcp-server

六、SKILL

In addition to the MCP server above, this project also provides an independent SKILL under the skill/ directory. The Skill can be deployed directly to Claude Code without relying on this MCP server (it calls ADB MySQL OpenAPI through call_adb_api.py in the SKILL directory).

The Skill covers cluster information queries, performance monitoring, slow query diagnosis, SQL Pattern analysis, and SQL execution, with built-in guided diagnostic workflows for common scenarios.

For setup and usage details, see skill/skill_readme.md.

Note: The evolution of this Skill will be aligned with our next-generation Agent in the future. Stay tuned.

License

Apache License 2.0