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:

> `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 ` 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

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

For OpenAPI management tools, add `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, and explicitly include `openapi` in `MCP_TOOLSETS`. The example below uses the common setting `MCP_TOOLSETS=openapi,sql`, so it also includes direct database connection settings and the SQL read tools work after copying the config:

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

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.

For full SQL execution through `execute_sql`, keep `MCP_TOOLSETS=sql` and set `ENABLE_SQL_WRITE_TOOLS=true`. Note that neither `MCP_TOOLSETS=sql` nor `MCP_TOOLSETS=all` enables full SQL execution by itself:

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alibabacloud-adb-mysql-mcp-server",
        "run",
        "adb-mysql-mcp-server"
      ],
      "env": {
        "MCP_TOOLSETS": "sql",
        "ENABLE_SQL_WRITE_TOOLS": "true",
        "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"
      }
    }
  }
}

If you need both OpenAPI management and full SQL execution, use `MCP_TOOLSETS=openapi,sql` and set `ENABLE_SQL_WRITE_TOOLS=true`:

{
  "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",
        "MCP_TOOLSETS": "openapi,sql",
        "ENABLE_SQL_WRITE_TOOLS": "true",
        "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 MCP_TOOLSETS=sql
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_HOST=127.0.0.1
export SERVER_PORT=8000
# API_KEY is required when SERVER_HOST is not a loopback address. Use at least 32 characters.
# export API_KEY="replace-with-a-random-token-at-least-32-chars"
# To enable OpenAPI management tools, add AK/SK and explicitly include openapi:
# export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
# export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# export MCP_TOOLSETS=openapi,sql
# To enable full SQL execution through execute_sql, explicitly set:
# export ENABLE_SQL_WRITE_TOOLS=true

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

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

If the server is bound to a non-loopback host, configure `API_KEY` on the server side and send it from the client side as an HTTP header. In short: `API_KEY` is the server-side token, and `Authorization: Bearer ` is the client-side request header.

# Server side
export SERVER_TRANSPORT=sse
export SERVER_HOST=0.0.0.0
export API_KEY="replace-with-a-random-token-at-least-32-chars"
uv --directory /path/to/alibabacloud-adb-mysql-mcp-server run adb-mysql-mcp-server

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "url": "http://your-server-host:8000/sse",
      "headers": {
        "Authorization": "Bearer replace-with-a-random-token-at-least-32-chars"
      }
    }
  }
}

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

export MCP_TOOLSETS=sql
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_HOST=127.0.0.1
export SERVER_PORT=8000
# API_KEY is required when SERVER_HOST is not a loopback address. Use at least 32 characters.
# export API_KEY="replace-with-a-random-token-at-least-32-chars"
# To enable OpenAPI management tools, add AK/SK and explicitly include openapi:
# export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
# export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# export MCP_TOOLSETS=openapi,sql
# To enable full SQL execution through execute_sql, explicitly set:
# export ENABLE_SQL_WRITE_TOOLS=true

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

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

For `streamable_http` on a non-loopback host, use the same server-side `API_KEY` and client-side `Authorization: Bearer ` header pattern shown above. Full client JSON configuration example:

{
  "mcpServers": {
    "adb-mysql-mcp-server": {
      "url": "http://your-server-host:8000/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-a-random-token-at-least-32-chars"
      }
    }
  }
}

> 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 MCP_TOOLSETS=sql
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_HOST=127.0.0.1
export SERVER_PORT=8000
# To enable OpenAPI management tools, add AK/SK and explicitly include openapi:
# export ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
# export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
# export MCP_TOOLSETS=openapi,sql

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"

2.4 Smoke Test

After the server is started and connected to your MCP client, run these read-only statements to verify the setup without modifying data:

select 1 as ok;

select current_date as today, current_timestamp as now_time;

You can also test query-plan tools with `get_query_plan` or `get_execution_plan`:

select 1 as plan_test;

In default read-only mode, the following multi-statement SQL should be rejected, which confirms single-statement protection is active:

select 1; select 2;

To further confirm write protection, run the following only in a test database or after confirming the table name. It should be rejected in default read-only mode:

update your_table set id = id where 1 = 0;

If you do not know a real table name yet, do not run table-specific SQL. Start with `show databases;`, the MCP resource `adbmysql:///databases`, or `adbmysql:///{database}/tables` to inspect metadata.

三、Environment Variables

四、Tool List

By default, only the `sql` group is enabled and `execute_sql` only allows read-only SQL. The `openapi` group is enabled only when `openapi` is explicitly included in `MCP_TOOLSETS`. `MCP_TOOLSETS` only controls tool-group exposure; full SQL execution through `execute_sql` must be enabled separately with `ENABLE_SQL_WRITE_TOOLS=true`.

4.1 Cluster Management (group: `openapi`)

4.2 Diagnostics & Monitoring (group: `openapi`)

4.3 Administration & Audit (group: `openapi`)

4.4 Advanced Diagnostics (group: `openapi`)

4.5 SQL Tools (group: `sql`)

4.6 MCP Resources (group: `sql`)

MCP resources are assigned to the `sql` group because they read database metadata through the SQL connection, such as `SHOW DATABASES`, `SHOW TABLES`, `SHOW CREATE TABLE`, and `SHOW adb_config`. They are read-only metadata resources and are available together with the default SQL read group.

五、Security Policy

5.1 Read-only SQL Mode

When `ENABLE_SQL_WRITE_TOOLS` is not set to `true`, `execute_sql` runs in read-only mode. The server validates SQL before opening a database connection:

• Allows read-only SQL such as `SELECT`, `SHOW`, `DESCRIBE`, `DESC`, `EXPLAIN`, and read-only `WITH` CTE statements.
• Allows one optional terminal semicolon and removes it before execution.
• Rejects multi-statement SQL.
• Rejects SQL comments outside strings or quoted identifiers.
• Rejects unclosed strings or quoted identifiers.
• Rejects write keywords in `SELECT` or `WITH` bodies, including nested write operations.
• Rejects `SELECT ... INTO OUTFILE` and `SELECT ... INTO DUMPFILE`.

This mode is intended to reduce accidental or unauthorized mutations by AI clients.

5.2 Full SQL Execution Mode

> Risk notice: Full SQL execution mode means the MCP server provides a general-purpose SQL execution entry point. After it is enabled, the server no longer attempts to classify SQL as read or write, and it does not block multi-statement SQL, comments, DDL, DML, DCL, or TCL. Enable it only for trusted users, trusted MCP clients, and least-privilege database accounts.

When `ENABLE_SQL_WRITE_TOOLS=true`, `execute_sql` becomes a full SQL execution entry point. The server only performs basic input validation: the value must be a string, must not be empty after trimming, and must not exceed `ADB_MYSQL_MAX_SQL_LENGTH`.

After this mode is enabled, the server no longer restricts statement type, comments, semicolons, multi-statement SQL, DDL, DML, DCL, or TCL, and it does not perform SQL syntax validation. Any SQL accepted by the configured database account and database driver may be executed.

`get_query_plan` and `get_execution_plan` are not full SQL execution tools. They always validate their input as a single read-only `SELECT` or read-only `WITH` CTE statement, even when `ENABLE_SQL_WRITE_TOOLS=true`.

5.3 Operational Recommendations

• Do not expose SSE or Streamable HTTP on a public or shared network without a strong `API_KEY`.
• Use high-entropy API keys and rotate them when they may have been shared.
• Use read-only database accounts for read-only deployments.
• Use least-privilege database accounts when full SQL execution is enabled.
• Enable OpenAPI tools only in trusted administration scenarios.

六、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 \
  -e ADB_MYSQL_HOST=your_adb_mysql_host \
  -e ADB_MYSQL_PORT=3306 \
  -e ADB_MYSQL_USER=your_username \
  -e ADB_MYSQL_PASSWORD=your_password \
  -e ADB_MYSQL_DATABASE=your_database \
  -e MCP_TOOLSETS=openapi,sql \
  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