Servidor MCP de AnalyticDB For MySQL

Servidor MCP de AnalyticDB for MySQL

Inglés | 中文

El Servidor MCP de AnalyticDB for MySQL es una interfaz universal entre Agentes de IA y AnalyticDB MySQL. Proporciona dos grupos de herramientas:

Herramientas y Recursos SQL (grupo sql): Conéctese directamente a los clústeres de ADB MySQL para ejecutar SQL, ver planes de ejecución y explorar metadatos de la base de datos. El grupo sql es solo un interruptor de grupo de herramientas; execute_sql se ejecuta en modo de solo lectura de forma predeterminada, y el modo de ejecución SQL completo requiere la configuración explícita adicional ENABLE_SQL_WRITE_TOOLS=true.
Herramientas OpenAPI (grupo openapi): Administre clústeres, listas blancas, cuentas, redes, monitoreo, diagnósticos y registros de auditoría a través de la OpenAPI de Alibaba Cloud.

Las herramientas de solo lectura están anotadas con ToolAnnotations(readOnlyHint=True) según el protocolo MCP, lo que permite a los clientes distinguirlas de las operaciones de mutación.

一、Requisitos previos

Python >= 3.13
uv (administrador de paquetes y ejecutor recomendado)
AccessKey de Alibaba Cloud (requerido para herramientas OpenAPI)
Opcional: Credenciales de conexión de ADB MySQL (para herramientas SQL en modo de conexión directa)

二、Inicio rápido

2.0 Elija una configuración

Elija los grupos de herramientas y los interruptores adicionales para su escenario antes de copiar una configuración de cliente:

Escenario	Grupos de herramientas	Interruptor adicional	Mejor para
Consultas SQL de solo lectura, EXPLAIN y exploración de metadatos	`sql`	Ninguno	Predeterminado recomendado para consultas, solución de problemas y análisis de solo lectura
Ejecución SQL completa a través de `execute_sql`	`sql`	`ENABLE_SQL_WRITE_TOOLS=true`	SQL INSERT/UPDATE/DELETE/DDL/multi-sentencia cuando el cliente MCP es confiable
Herramientas de administración de clústeres OpenAPI + herramientas de lectura SQL	`openapi,sql`	AK/SK de Alibaba Cloud + configuración de conexión directa `ADB_MYSQL_*`	Operaciones de clúster, cuentas, listas blancas, diagnósticos y monitoreo mientras se mantiene el acceso de lectura SQL
OpenAPI + ejecución SQL completa	`openapi,sql`	AK/SK de Alibaba Cloud + configuración de conexión directa `ADB_MYSQL_*` + `ENABLE_SQL_WRITE_TOOLS=true`	Administración más ejecución SQL completa

MCP_TOOLSETS=sql solo habilita el grupo de herramientas SQL. La ejecución SQL completa no es un grupo de herramientas separado, y no existe un grupo de herramientas sql_write. Debe habilitarse por separado con ENABLE_SQL_WRITE_TOOLS=true.

Antes de configurar un cliente, verifique:

Modo de base de datos directa: configure ADB_MYSQL_HOST, ADB_MYSQL_PORT, ADB_MYSQL_USER, ADB_MYSQL_PASSWORD y opcionalmente ADB_MYSQL_DATABASE.
Modo de cuenta temporal: si ADB_MYSQL_USER / ADB_MYSQL_PASSWORD no están configurados pero AK/SK está disponible, el servidor crea una cuenta de base de datos temporal a través de OpenAPI; las llamadas a herramientas SQL deben proporcionar region_id y db_cluster_id.
SSE remoto / HTTP transmisible: cuando SERVER_HOST no es una dirección de bucle local, configure API_KEY en el servidor y Authorization: Bearer <API_KEY> en el cliente.
Ejecución SQL completa: habilítela solo para usuarios confiables y clientes MCP confiables, y use una cuenta de base de datos con privilegios mínimos.

2.1 Uso de cherry-studio (Recomendado)

Descargue e instale cherry-studio
Siga la documentación para instalar uv, que es necesario para el entorno MCP
Configure y use ADB MySQL MCP según la documentación. Puede importar rápidamente la configuración usando el JSON a continuación.

cherry-studio configuration

Configuración A — Solo herramientas de lectura SQL (ejecutar consultas de solo lectura, ver planes, explorar metadatos):

{
  "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"
      }
    }
  }
}

Configuración B — Herramientas OpenAPI + herramientas de lectura SQL:

Nota: Las herramientas OpenAPI incluyen capacidades de administración de mutación como creación de cuentas, modificación de listas blancas y terminación de consultas. Habilítelas solo cuando necesite intencionalmente operaciones de administración. El ejemplo a continuación también mantiene habilitado el grupo de herramientas sql, por lo que incluye configuraciones de conexión directa a la base de datos.

{
  "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"
      }
    }
  }
}

Si solo desea herramientas de administración OpenAPI y no necesita herramientas o recursos SQL, cambie MCP_TOOLSETS a openapi y elimine la configuración de base de datos directa ADB_MYSQL_*.

Configuración C — Ejecución SQL completa a través de execute_sql:

Advertencia: Con ENABLE_SQL_WRITE_TOOLS=true, execute_sql expone la ejecución SQL completa. El servidor solo realiza validación básica de entrada y no restringe el tipo de sentencia, comentarios, punto y coma, SQL multi-sentencia, DDL, DML, DCL o TCL. Habilítelo solo para usuarios confiables y use una cuenta de base de datos con privilegios mínimos.

{
  "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"
      }
    }
  }
}

Configuración D — Herramientas OpenAPI + ejecución SQL completa:

Advertencia: Esta configuración habilita tanto las capacidades de administración OpenAPI como la ejecución SQL completa a través de execute_sql. Úsela solo con clientes confiables, usuarios confiables y una cuenta de base de datos con privilegios mínimos.

{
  "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"
      }
    }
  }
}

Sin MCP_TOOLSETS, solo el grupo sql está habilitado, y execute_sql aún se ejecuta en modo de solo lectura de forma predeterminada. Cuando AK/SK no está configurado, las herramientas OpenAPI se deshabilitan automáticamente incluso si se solicitan.

2.2 Uso de Claude Code

Descargue desde GitHub y sincronice dependencias:

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

Agregue la siguiente configuración al archivo de configuración MCP de Claude Code (nivel de proyecto: .mcp.json en la raíz del proyecto, o nivel de usuario: ~/.claude/settings.json):

Transporte stdio:

{
  "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"
      }
    }
  }
}

Para herramientas de administración OpenAPI, agregue ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET e incluya explícitamente openapi en MCP_TOOLSETS. El ejemplo a continuación usa la configuración común MCP_TOOLSETS=openapi,sql, por lo que también incluye configuraciones de conexión directa a la base de datos y las herramientas de lectura SQL funcionan después de copiar la configuración:

{
  "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"
      }
    }
  }
}

Si solo desea herramientas de administración OpenAPI y no necesita herramientas o recursos SQL, cambie MCP_TOOLSETS a openapi y elimine la configuración de base de datos directa ADB_MYSQL_*.

Para ejecución SQL completa a través de execute_sql, mantenga MCP_TOOLSETS=sql y establezca ENABLE_SQL_WRITE_TOOLS=true. Tenga en cuenta que ni MCP_TOOLSETS=sql ni MCP_TOOLSETS=all habilitan la ejecución SQL completa por sí solos:

{
  "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"
      }
    }
  }
}

Si necesita tanto administración OpenAPI como ejecución SQL completa, use MCP_TOOLSETS=openapi,sql y establezca 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"
      }
    }
  }
}

Transporte SSE — inicie el servidor primero, luego configure el cliente:

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"
    }
  }
}

Si el servidor está vinculado a un host que no es de bucle local, configure API_KEY en el lado del servidor y envíelo desde el lado del cliente como un encabezado HTTP. En resumen: API_KEY es el token del lado del servidor, y Authorization: Bearer <API_KEY> es el encabezado de solicitud del lado del cliente.

# 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"
      }
    }
  }
}

Transporte HTTP transmisible — inicie el servidor primero, luego configure el cliente:

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"
    }
  }
}

Para streamable_http en un host que no es de bucle local, use el mismo patrón de API_KEY del lado del servidor y encabezado Authorization: Bearer <API_KEY> del lado del cliente que se muestra arriba. Ejemplo completo de configuración JSON del cliente:

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

Nota: Cuando ADB_MYSQL_USER y ADB_MYSQL_PASSWORD no están configurados pero AK/SK está disponible, se crea automáticamente una cuenta de base de datos temporal a través de OpenAPI para la ejecución SQL y se limpia después.

2.3 Uso de Cline

Establezca variables de entorno y ejecute el servidor MCP:

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

Luego configure el servidor remoto de Cline:

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

2.4 Prueba de humo

Después de que el servidor esté iniciado y conectado a su cliente MCP, ejecute estas sentencias de solo lectura para verificar la configuración sin modificar datos:

select 1 as ok;

select current_date as today, current_timestamp as now_time;

También puede probar las herramientas de plan de consulta con get_query_plan o get_execution_plan:

select 1 as plan_test;

En el modo de solo lectura predeterminado, el siguiente SQL multi-sentencia debería ser rechazado, lo que confirma que la protección de sentencia única está activa:

select 1; select 2;

Para confirmar aún más la protección de escritura, ejecute lo siguiente solo en una base de datos de prueba o después de confirmar el nombre de la tabla. Debería ser rechazado en el modo de solo lectura predeterminado:

update your_table set id = id where 1 = 0;

Si aún no conoce un nombre de tabla real, no ejecute SQL específico de tablas. Comience con show databases;, el recurso MCP adbmysql:///databases o adbmysql:///{database}/tables para inspeccionar metadatos.

三、Variables de entorno

Variable	Requerida	Descripción
`ALIBABA_CLOUD_ACCESS_KEY_ID`	Sí (herramientas OpenAPI)	ID de AccessKey de Alibaba Cloud
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Sí (herramientas OpenAPI)	Secreto de AccessKey de Alibaba Cloud
`ALIBABA_CLOUD_SECURITY_TOKEN`	No	Token de seguridad temporal STS
`ADB_MYSQL_HOST`	No	Host de la base de datos (modo de conexión directa)
`ADB_MYSQL_PORT`	No	Puerto de la base de datos, predeterminado 3306 (modo de conexión directa)
`ADB_MYSQL_USER`	No	Nombre de usuario de la base de datos (modo de conexión directa)
`ADB_MYSQL_PASSWORD`	No	Contraseña de la base de datos (modo de conexión directa)
`ADB_MYSQL_DATABASE`	No	Nombre de base de datos predeterminado (modo de conexión directa)
`ADB_MYSQL_CONNECT_TIMEOUT`	No	Tiempo de espera de conexión de la base de datos en segundos, predeterminado 2
`ADB_MYSQL_MAX_SQL_LENGTH`	No	Longitud máxima aceptada de sentencias SQL, predeterminado 10000. Debe ser un entero positivo
`ADB_API_CONNECT_TIMEOUT`	No	Tiempo de espera de conexión OpenAPI en milisegundos, predeterminado 10000 (10s)
`ADB_API_READ_TIMEOUT`	No	Tiempo de espera de lectura OpenAPI en milisegundos, predeterminado 300000 (5min)
`MCP_TOOLSETS`	No	Grupos de herramientas separados por comas para habilitar. Predeterminado: `sql`. Grupos admitidos: `sql`, `openapi`; atajo: `all` se expande a `openapi,sql`. Esta variable solo controla la exposición del grupo de herramientas y no controla el permiso de ejecución SQL completa
`SERVER_TRANSPORT`	No	Protocolo de transporte: `stdio` (predeterminado), `sse`, `streamable_http`
`SERVER_HOST`	No	Host de enlace SSE/HTTP, predeterminado `127.0.0.1`; los hosts que no son de bucle local requieren `API_KEY`
`SERVER_PORT`	No	Puerto del servidor SSE/HTTP, predeterminado 8000
`API_KEY`	No	Token de autenticación HTTP MCP; los clientes deben enviar `Authorization: Bearer <API_KEY>` cuando esté configurado. Requerido en hosts que no son de bucle local; use al menos 32 caracteres
`ENABLE_SQL_WRITE_TOOLS`	No	Controla si `execute_sql` entra en modo de ejecución SQL completa. Predeterminado: `false`; debe establecerse explícitamente a `true` para entrar en modo de ejecución SQL completa. El alcance real ejecutable aún está limitado por los privilegios de la cuenta de la base de datos, el controlador de la base de datos y la longitud máxima de SQL

四、Lista de herramientas

De forma predeterminada, solo el grupo sql está habilitado y execute_sql solo permite SQL de solo lectura. El grupo openapi se habilita solo cuando openapi se incluye explícitamente en MCP_TOOLSETS. MCP_TOOLSETS solo controla la exposición del grupo de herramientas; la ejecución SQL completa a través de execute_sql debe habilitarse por separado con ENABLE_SQL_WRITE_TOOLS=true.

4.1 Administración de clústeres (grupo: `openapi`)

Herramienta	Descripción
`describe_db_clusters`	Listar clústeres de ADB MySQL en una región
`describe_db_cluster_attribute`	Obtener atributos detallados del clúster
`describe_cluster_access_whitelist`	Obtener lista blanca de IP del clúster
`modify_cluster_access_whitelist`	Modificar lista blanca de IP del clúster
`describe_accounts`	Listar cuentas de base de datos en un clúster
`describe_cluster_net_info`	Obtener información de conexión de red del clúster
`get_current_time`	Obtener hora actual del servidor

4.2 Diagnósticos y monitoreo (grupo: `openapi`)

Herramienta	Descripción
`describe_db_cluster_performance`	Consultar métricas de rendimiento del clúster (CPU, memoria, QPS, etc.)
`describe_db_cluster_health_status`	Consultar estado de salud del clúster
`describe_diagnosis_records`	Consultar registros de resumen de diagnóstico SQL
`describe_diagnosis_sql_info`	Obtener detalles de ejecución SQL (plan, información de tiempo de ejecución)
`describe_bad_sql_detection`	Detectar SQL malo que afecta la estabilidad del clúster
`describe_sql_patterns`	Consultar lista de patrones SQL
`describe_table_statistics`	Consultar estadísticas a nivel de tabla

4.3 Administración y auditoría (grupo: `openapi`)

Herramienta	Descripción
`create_account`	Crear una cuenta de base de datos
`modify_db_cluster_description`	Modificar descripción del clúster
`describe_db_cluster_space_summary`	Obtener resumen de espacio de almacenamiento del clúster
`describe_audit_log_records`	Consultar registros de auditoría SQL

4.4 Diagnósticos avanzados (grupo: `openapi`)

Herramienta	Descripción
`describe_executor_detection`	Diagnóstico de nodos de cómputo
`describe_worker_detection`	Diagnóstico de nodos de almacenamiento
`describe_controller_detection`	Diagnóstico de nodos de acceso
`describe_available_advices`	Obtener recomendaciones de optimización
`kill_process`	Terminar un proceso de consulta en ejecución
`describe_db_resource_group`	Obtener configuración del grupo de recursos
`describe_excessive_primary_keys`	Detectar tablas con claves primarias excesivas
`describe_oversize_non_partition_table_infos`	Detectar tablas no particionadas de gran tamaño
`describe_table_partition_diagnose`	Diagnosticar problemas de particionamiento de tablas
`describe_inclined_tables`	Detectar tablas con sesgo de datos

4.5 Herramientas SQL (grupo: `sql`)

Herramienta	Descripción
`execute_sql`	Ejecutar SQL en un clúster ADB MySQL. Por defecto solo se permite SQL de solo lectura; la ejecución completa de SQL requiere `ENABLE_SQL_WRITE_TOOLS=true`
`get_query_plan`	Obtener el plan de ejecución EXPLAIN para una sola sentencia SELECT o una CTE de solo lectura
`get_execution_plan`	Obtener el plan de ejecución real EXPLAIN ANALYZE para una sola sentencia SELECT o una CTE de solo lectura

4.6 Recursos MCP (grupo: `sql`)

Los recursos MCP se asignan al grupo sql porque leen metadatos de la base de datos a través de la conexión SQL, como SHOW DATABASES, SHOW TABLES, SHOW CREATE TABLE y SHOW adb_config. Son recursos de metadatos de solo lectura y están disponibles junto con el grupo de lectura SQL predeterminado.

URI del recurso	Descripción
`adbmysql:///databases`	Listar todas las bases de datos
`adbmysql:///{database}/tables`	Listar todas las tablas en una base de datos
`adbmysql:///{database}/{table}/ddl`	Obtener el DDL de una tabla
`adbmysql:///config/{key}/value`	Obtener el valor de una clave de configuración

五、Política de Seguridad

5.1 Modo SQL de Solo Lectura

Cuando ENABLE_SQL_WRITE_TOOLS no está establecido en true, execute_sql se ejecuta en modo de solo lectura. El servidor valida el SQL antes de abrir una conexión a la base de datos:

Permite SQL de solo lectura como SELECT, SHOW, DESCRIBE, DESC, EXPLAIN y sentencias CTE de solo lectura WITH.
Permite un punto y coma final opcional y lo elimina antes de la ejecución.
Rechaza sentencias SQL múltiples.
Rechaza comentarios SQL fuera de cadenas o identificadores entre comillas.
Rechaza cadenas o identificadores entre comillas sin cerrar.
Rechaza palabras clave de escritura en cuerpos de SELECT o WITH, incluidas operaciones de escritura anidadas.
Rechaza SELECT ... INTO OUTFILE y SELECT ... INTO DUMPFILE.

Este modo tiene como objetivo reducir mutaciones accidentales o no autorizadas por parte de clientes de IA.

5.2 Modo de Ejecución Completa de SQL

Aviso de riesgo: El modo de ejecución completa de SQL significa que el servidor MCP proporciona un punto de entrada de ejecución SQL de propósito general. Una vez habilitado, el servidor ya no intenta clasificar el SQL como lectura o escritura, y no bloquea sentencias SQL múltiples, comentarios, DDL, DML, DCL o TCL. Habilítelo solo para usuarios de confianza, clientes MCP de confianza y cuentas de base de datos con privilegios mínimos.

Cuando ENABLE_SQL_WRITE_TOOLS=true, execute_sql se convierte en un punto de entrada de ejecución completa de SQL. El servidor solo realiza una validación básica de entrada: el valor debe ser una cadena, no debe estar vacío después de recortar espacios y no debe exceder ADB_MYSQL_MAX_SQL_LENGTH.

Después de habilitar este modo, el servidor ya no restringe el tipo de sentencia, comentarios, puntos y comas, sentencias SQL múltiples, DDL, DML, DCL o TCL, y no realiza validación de sintaxis SQL. Cualquier SQL aceptado por la cuenta de base de datos y el controlador de base de datos configurados puede ejecutarse.

get_query_plan y get_execution_plan no son herramientas de ejecución completa de SQL. Siempre validan su entrada como una sola sentencia CTE de solo lectura SELECT o de solo lectura WITH, incluso cuando ENABLE_SQL_WRITE_TOOLS=true.

5.3 Recomendaciones Operativas

No exponga SSE o HTTP Streamable en una red pública o compartida sin un API_KEY fuerte.
Use claves API de alta entropía y rótelas cuando puedan haber sido compartidas.
Use cuentas de base de datos de solo lectura para implementaciones de solo lectura.
Use cuentas de base de datos con privilegios mínimos cuando la ejecución completa de SQL esté habilitada.
Habilite las herramientas OpenAPI solo en escenarios de administración de confianza.

六、Desarrollo Local

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

Ejecutar pruebas:

uv run python -m pytest test/ -v

Depurar con 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

Además del servidor MCP anterior, este proyecto también proporciona un SKILL independiente bajo el directorio skill/. El Skill se puede implementar directamente en Claude Code sin depender de este servidor MCP (llama a ADB MySQL OpenAPI a través de call_adb_api.py en el directorio SKILL).

El Skill cubre consultas de información de clústeres, monitoreo de rendimiento, diagnóstico de consultas lentas, análisis de patrones SQL y ejecución de SQL, con flujos de trabajo de diagnóstico guiados integrados para escenarios comunes.

Para detalles de configuración y uso, consulte skill/skill_readme.md.

Nota: La evolución de este Skill estará alineada con nuestro Agente de próxima generación en el futuro. Manténgase atento.

Licencia

Apache License 2.0

AnalyticDB for MySQL

Documentación