GaussDB MCP

Servidor MCP para la base de datos en la nube GaussDB de Huawei Cloud. Basado en el controlador Node.js oficial de GaussDB gaussdb-node, siguiendo la especificación MCP 2026-07-28, proporciona 24 herramientas y 1 recurso de estructura de tabla para prueba de conexión, consulta, escritura de datos, transacciones, metadatos, diagnóstico y operación, y permisos de usuario.

Inicio rápido

npm install
cp .env.example .env   # Windows: copy .env.example .env 后编辑
# 编辑 .env,填入 GaussDB 实例地址、密码等
npm run build
node build/index.js    # 启动(stdio,供 MCP 客户端拉起)

Requiere Node.js ≥ 20.

Related MCP server: mcp-db-assistant

Configuración de conexión

Todas las variables de entorno

Configuración de conexión de red interna

Se usa cuando la aplicación y la instancia GaussDB están en la misma VPC. No se requiere SSL (el tráfico de la red interna no sale, Huawei Cloud oficialmente usa conexión directa interna por defecto):

GAUSSDB_HOST=10.0.1.11              # 实例"节点列表"中的内网地址
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
# 不设置任何 GAUSSDB_SSL_* 变量,保持 GAUSSDB_SSL=0(默认)

Configuración de conexión de red pública

Se usa cuando la aplicación no está en la VPC de la instancia y accede a través de una IP elástica pública. Debe habilitar SSL y configurar el certificado CA (método oficial de Huawei Cloud sslmode=verify-ca):

GAUSSDB_HOST=114.114.114.114        # 实例绑定的弹性公网 IP
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
GAUSSDB_SSL=1
GAUSSDB_SSL_CA=C:/path/to/root.crt   # 华为云控制台下载的 CA 证书(公网连接必需)
GAUSSDB_SSL_REJECT_UNAUTHORIZED=true

Antes de la conexión de red pública, también debe permitir el acceso del IP de salida del cliente al puerto 8000 en el grupo de seguridad de la consola de Huawei Cloud.

Cómo agregar variables de entorno

Dos formas, elija una (si ambas existen, las variables de entorno tienen prioridad sobre .env):

1. Archivo .env del proyecto (recomendado): copie .env.example como .env en la raíz del proyecto y complételo. La ubicación de .env está anclada a la raíz del proyecto, independientemente del directorio desde el que se inicie el servidor: el cliente MCP puede leerlo desde cualquier directorio de trabajo al iniciar build/index.js. Las dos configuraciones anteriores se pueden escribir directamente en .env.

2. Campo env del cliente MCP: pase las variables de entorno directamente en la configuración de mcpServers (ver ejemplos de integración más abajo), adecuado para escenarios donde no se desea colocar archivos de credenciales en el proyecto.

En despliegues primario/secundario, GAUSSDB_HOST separa las IP de múltiples nodos con comas en inglés; al iniciar, el servidor intenta conectarse secuencialmente y selecciona automáticamente el primer nodo disponible.

Resumen de herramientas (24)

Todas las herramientas están marcadas con anotaciones según la especificación MCP (readOnlyHint/destructiveHint), el cliente puede mostrar confirmación para operaciones de escritura según esto.

Conexión y estado

Consulta y escritura

Transacciones (modo de manejo explícito)

Uso: transaction_begin → múltiples query/execute (pasando el mismo tx_handle) → transaction_commit o transaction_rollback.

Metadatos (solo lectura)

Diagnóstico y operación (solo lectura)

Usuarios y permisos

Recursos

Integración con el cliente MCP

Después de compilar, regístrelo en el archivo de configuración del cliente (usando el formato mcpServers de Claude Desktop / Cursor como ejemplo). En Windows use rutas con doble barra invertida (E:\\MCP\\GaussDBMCP\\build\\index.js), en Linux/macOS use barras normales (/home/user/GaussDBMCP/build/index.js).

Integración de conexión de red interna

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "10.0.1.11",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码"
      }
    }
  }
}

La conexión de red interna no requiere SSL, no es necesario configurar ninguna variable GAUSSDB_SSL_*.

Integración de conexión de red pública

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "114.114.114.114",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码",
        "GAUSSDB_SSL": "1",
        "GAUSSDB_SSL_CA": "C:\\path\\to\\root.crt",
        "GAUSSDB_SSL_REJECT_UNAUTHORIZED": "true"
      }
    }
  }
}

La conexión de red pública debe habilitar SSL y configurar el certificado CA, y asegurarse de que el grupo de seguridad permita el puerto 8000 para la IP de salida del cliente.

También puede omitir env y depender del archivo .env en la raíz del proyecto (se lee automáticamente al iniciar el servidor, anclado a la raíz del proyecto, independiente del directorio de inicio).

Aislamiento multiinquilino (stream = schema)

GAUSSDB_SEARCH_PATH también actúa como lista blanca de esquemas a nivel MCP: una vez configurado, el acceso se limita al esquema propio del stream correspondiente, no se ven las tablas de otros streams.

Intercepción a nivel MCP (confiable, basada en parámetros estructurales):

• list_schemas solo devuelve los esquemas en la lista blanca, no filtra otros nombres de esquema

• list_tables/list_indexes/list_views/list_sequences cuando no se pasa schema, se fijan por defecto al primer esquema de la lista blanca, ya no devuelven tablas de toda la base de datos

• describe_table/insert_rows/update_rows/delete_rows cuando se pasa schema explícitamente, si no está en la lista blanca, se rechaza con error

• El recurso de estructura de tabla gaussdb://{schema}/{table}/schema también está sujeto a la lista blanca, la lectura entre esquemas se rechaza

Capa de respaldo de permisos de base de datos (obligatoria, no se puede omitir): execute es SQL arbitrario, la capa MCP no analiza SQL (un analizador escrito a mano siempre tendrá rutas de evasión); aunque query fuerza solo lectura (lista blanca de palabras clave iniciales + lista negra de palabras clave de escritura + rechazo de múltiples declaraciones), las funciones con efectos secundarios en forma de SELECT (como pg_terminate_backend, setval) no se pueden interceptar exhaustivamente. El acceso entre esquemas y las funciones con efectos secundarios están garantizados por los permisos de GaussDB. Cada stream usa una cuenta restringida independiente, autorizando solo su propio esquema:

-- 以管理员执行:为 stream 建受限账号,只授予自己 schema 的权限
CREATE USER gycwd_app WITH PASSWORD 'xxx' LOGIN;
REVOKE ALL ON DATABASE postgres FROM PUBLIC;            -- 收紧库级默认权限
GRANT CONNECT ON DATABASE postgres TO gycwd_app;
GRANT USAGE ON SCHEMA gycwd TO gycwd_app;               -- 只给自己的 schema
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA gycwd TO gycwd_app;
-- 该账号未授予其他 schema 的 USAGE,即使手写跨 schema SQL 也会被数据库拒绝

Luego en .env establezca GAUSSDB_USER=gycwd_app, GAUSSDB_SEARCH_PATH=gycwd, dos capas superpuestas: la entrada estructural la intercepta MCP, el SQL arbitrario lo intercepta la base de datos.

Notas de seguridad

• Los registros del servidor stdio se escriben en stderr, stdout solo transporta mensajes MCP

• Los identificadores (nombres de tabla, columna, usuario, etc.) de las herramientas estructuradas (insert_rows/update_rows/delete_rows, etc.) se validan con caracteres, los valores siempre usan marcadores de posición parametrizados para prevenir inyección SQL; query/explain_query son entradas SQL libres, restringidas por validación de solo lectura y límite de una sola declaración (ver arriba)

• delete_rows/update_rows requieren obligatoriamente una condición where

• explain_query con analyze=true ejecuta realmente la declaración, solo permite que comience con SELECT/WITH y envuelve automáticamente en una transacción revertida (el avance de secuencias y los efectos secundarios de funciones no se pueden revertir)

• Declaraciones como DROP/TRUNCATE se pueden ejecutar mediante execute, el cliente debe confiar en la anotación destructiveHint para confirmación

• No envíe .env al repositorio de versiones

Desarrollo y compilación

npm run build   # tsc 编译到 build/

Estructura del código fuente: src/config.ts (configuración), src/db.ts (pool de conexiones y manejadores de transacciones), src/sql.ts (construcción de SQL y validación de solo lectura), src/format.ts (formateo de resultados), src/index.ts (servidor MCP y registro de herramientas).

Después de obtener una instancia real de GaussDB: complete .env → npm run build → node build/index.js y pruébelo con cualquier cliente MCP; o primero verifique la conexión por separado: configure env y ejecute la herramienta test_connection.