AnalyticDB for MySQL MCP Server is a universal interface between AI Agents and AnalyticDB MySQL. It provides two tool groups:
SQL Tools & Resources ( group): Connect directly to ADB MySQL clusters to execute SQL, view execution plans, and browse database metadata. The group is only a tool-group switch; runs in read-only mode by default, and full SQL execution mode requires the additional explicit setting .
AnalyticDB for MySQL MCP Server
2026-10-28
ดาว
32
เครื่องมือ
—
อัปไทม์
—
sql
sql
execute_sql
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.
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.
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.
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.
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.
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):
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:
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:
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 <API_KEY> 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
For streamable_http on a non-loopback host, use the same server-side API_KEY and client-side Authorization: Bearer <API_KEY> header pattern shown above. Full client JSON configuration example:
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.
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.
Maximum accepted SQL statement length, default 10000. Must be a positive integer
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)
MCP_TOOLSETS
No
Comma-separated tool groups to enable. Default: sql. Supported groups: sql, openapi; shortcut: all expands to openapi,sql. This variable only controls tool-group exposure and does not control full SQL execution permission
SERVER_TRANSPORT
No
Transport protocol: stdio (default), sse, streamable_http
MCP HTTP auth token; clients must send Authorization: Bearer <API_KEY> when configured. Required on non-loopback hosts; use at least 32 characters
ENABLE_SQL_WRITE_TOOLS
No
Controls whether execute_sql enters full SQL execution mode. Default: false; it must be explicitly set to true to enter full SQL execution mode. The actual executable scope is still limited by the database account privileges, database driver, and maximum SQL length
四、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.
Execute SQL on an ADB MySQL cluster. Read-only SQL is allowed by default; full SQL execution requires ENABLE_SQL_WRITE_TOOLS=true
get_query_plan
Get EXPLAIN execution plan for a single SELECT or read-only WITH CTE statement
get_execution_plan
Get EXPLAIN ANALYZE actual execution plan for a single SELECT or read-only WITH CTE statement
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.
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
五、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
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.