AnalyticDB for MySQL MCP Server

English | 中文

AnalyticDB for MySQL MCP Server is a universal interface between AI Agents and AnalyticDB MySQL. It provides two tool groups:

- SQL Tools & Resources (sql group): Connect directly to ADB MySQL clusters to execute SQL, view execution plans, and browse database metadata. The sql group is only a tool-group switch; execute_sql runs in read-only mode by default, and full SQL execution mode requires the additional explicit setting ENABLE_SQL_WRITE_TOOLS=true.
- OpenAPI Tools (openapi group): Manage clusters, whitelists, accounts, networking, monitoring, diagnostics, and audit logs via Alibaba Cloud OpenAPI.

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.0 Choose a Configuration

Choose the tool groups and extra switches for your scenario before copying a client configuration:

| Scenario | Tool groups | Extra switch | Best for |
| --- | --- | --- | --- |
| Read-only SQL queries, EXPLAIN, and metadata browsing | sql | None | Recommended default for querying, troubleshooting, and read-only analysis |
| Full SQL execution through execute_sql | sql | ENABLE_SQL_WRITE_TOOLS=true | INSERT/UPDATE/DELETE/DDL/multi-statement SQL when the MCP client is trusted |
| OpenAPI cluster management tools + SQL read tools | openapi,sql | Alibaba Cloud AK/SK + ADB_MYSQL_ direct connection settings | Cluster, account, whitelist, diagnostics, and monitoring operations while keeping SQL read access |
| OpenAPI + full SQL execution | openapi,sql | Alibaba Cloud AK/SK + ADB_MYSQL_ direct connection settings + ENABLE_SQL_WRITE_TOOLS=true | Administration plus full SQL execution |

> MCP_TOOLSETS=sql only enables the SQL tool group. Full SQL execution is not a separate tool group, and there is no sql_write tool group. It must be enabled separately with ENABLE_SQL_WRITE_TOOLS=true.

Before configuring a client, check:

- Direct database mode: configure ADB_MYSQL_HOST, ADB_MYSQL_PORT, ADB_MYSQL_USER, ADB_MYSQL_PASSWORD, and optionally ADB_MYSQL_DATABASE.
- Temporary account mode: if ADB_MYSQL_USER / ADB_MYSQL_PASSWORD are not configured but AK/SK is available, the server creates a temporary database account through OpenAPI; SQL tool calls must provide region_id and db_cluster_id.
- Remote SSE / Streamable HTTP: when SERVER_HOST is not a loopback address, configure API_KEY on the server and Authorization: Bearer <API_KEY> on the client.
- Full SQL execution: enable it only for trusted users and trusted MCP clients, and use a least-privilege database account.

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 read tools only (execute read-only 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",
        "MCP_TOOLSETS": "sql"
      }
    }
  }
}

Configuration B — OpenAPI tools + SQL read tools:

> Note: OpenAPI tools include mutating administration capabilities such as account creation, whitelist modification, and query termination. Enable them only when you intentionally need management operations. The example below also keeps the sql tool group enabled, so it includes direct database connection settings.

{
  "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",
        "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",
        "MCP_TOOLSETS": "openapi,sql"
      }
    }
  }
}

If you only want OpenAPI management tools and do not need SQL tools or resources, change MCP_TOOLSETS to openapi and remove the ADB_MYSQL_* direct database settings.

Configuration C — Full SQL execution through execute_sql:

> Warning: With ENABLE_SQL_WRITE_TOOLS=true, execute_sql exposes full SQL execution. The server only performs basic input validation and does not restrict statement type, comments, semicolons, multi-statement SQL, DDL, DML, DCL, or TCL. Enable it only for trusted users and use a least-privilege database account.

{
  "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",
        "MCP_TOOLSETS": "sql",
        "ENABLE_SQL_WRITE_TOOLS": "true"
      }
    }
  }
}

Configuration D — OpenAPI tools + full SQL execution:

> Warning: This configuration enables both OpenAPI management capabilities and full SQL execution through execute_sql. Use it only with trusted clients, trusted users, and a least-privilege database account.

{
  "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",
        "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",
        "MCP_TOOLSETS": "openapi,sql",
        "ENABLE_SQL_WRITE_TOOLS": "true"
      }
    }
  }
}

> Without MCP_TOOLSETS, only the sql group is enabled, and execute_sql still runs in read-only mode by default. When AK/SK is not configured, OpenAPI tools are automatically disabled even if requested.

2.2 Using Claude Code

…