GaussDB MCP

华为云 GaussDB 云数据库 MCP 服务器。基于华为官方 GaussDB 专属 Node.js 驱动 gaussdb-node,遵循 MCP 2026-07-28 规范,提供连接测试、查询、数据写入、事务、元数据、诊断运维、用户权限等 24 个工具与 1 个表结构资源。

快速开始

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

要求 Node.js ≥ 20。

Related MCP server: mcp-db-assistant

连接配置

全部环境变量

内网连接配置

应用与 GaussDB 实例在同一 VPC 内时使用。不需要 SSL(内网流量不外泄,华为云官方默认内网直连):

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

公网连接配置

应用不在实例 VPC 内、通过弹性公网 IP 访问时使用。必须开启 SSL 并配置 CA 证书(华为云官方 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

公网连接前还需在华为云控制台安全组中放行客户端出口 IP 对 8000 端口的访问。

环境变量如何添加

两种方式,任选其一(同时存在时环境变量优先于 .env):

1. 项目 .env 文件(推荐):把 .env.example 复制为项目根目录下的 .env 并填写。.env 的定位锚定项目根目录,与服务器从哪个目录启动无关——MCP 客户端从任何工作目录拉起 build/index.js 都能读到。上面两种配置直接写入 .env 即可。

2. MCP 客户端 env 字段:在 mcpServers 配置里直接传环境变量(见下文接入示例),适合不想在项目里放凭据文件的场景。

主备部署时 GAUSSDB_HOST 用英文逗号分隔多个节点 IP,服务器启动时依次试连,自动选用第一个可用节点。

工具一览(24 个)

所有工具按 MCP 规范标注了 annotations(readOnlyHint/destructiveHint),客户端可据此对写操作弹出确认。

连接与状态

查询与写入

事务(显式 handle 模式)

用法:transaction_begin → 多次 query/execute(传入同一 tx_handle)→ transaction_commit 或 transaction_rollback。

元数据(只读)

诊断运维(只读)

用户与权限

资源

MCP 客户端接入

构建后在客户端配置文件中注册(以 Claude Desktop / Cursor 的 mcpServers 格式为例)。Windows 用双反斜杠路径(E:\\MCP\\GaussDBMCP\\build\\index.js),Linux/macOS 用正斜杠(/home/user/GaussDBMCP/build/index.js)。

内网连接接入

{
  "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": "你的密码"
      }
    }
  }
}

内网连接不需要 SSL,不设置任何 GAUSSDB_SSL_* 变量即可。

公网连接接入

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

公网连接必须开启 SSL 并配置 CA 证书,并确保安全组放行客户端出口 IP 的 8000 端口。

也可不传 env,依赖项目根目录下 .env 文件(服务器启动时自动读取,锚定项目根,与启动目录无关)。

多租户隔离(stream = schema)

GAUSSDB_SEARCH_PATH 同时充当 MCP 层 schema 白名单:配置后访问被限制在对应 stream 自己的 schema 内,看不到其他 stream 的表。

MCP 层拦截(可靠,靠结构参数):

• list_schemas 只返回白名单内的 schema,不泄露其他 schema 名

• list_tables/list_indexes/list_views/list_sequences 不传 schema 时默认钉到首个白名单 schema,不再返回全库表

• describe_table/insert_rows/update_rows/delete_rows 显式传 schema 时,若不在白名单内直接报错拒绝

• 表结构资源 gaussdb://{schema}/{table}/schema 同样受白名单约束,跨 schema 读取被拒

数据库权限层兜底(必需,不可省):execute 是任意 SQL,MCP 层不做 SQL 解析(手写解析器必有绕过路径);query 虽强制只读(首关键字白名单 + 写关键字黑名单 + 拒绝多语句),但 SELECT 形式的有副作用函数(如 pg_terminate_backend、setval)无法穷举拦截。跨 schema 访问与副作用函数由 GaussDB 权限保证。每个 stream 用独立受限账号,只授权自己的 schema:

-- 以管理员执行:为 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 也会被数据库拒绝

然后 .env 里 GAUSSDB_USER=gycwd_app、GAUSSDB_SEARCH_PATH=gycwd,两层叠加:结构入口 MCP 拦、任意 SQL 数据库拦。

安全说明

• stdio 服务器日志全部写 stderr,stdout 仅承载 MCP 消息

• 结构化工具(insert_rows/update_rows/delete_rows 等)的表名/列名/用户名等标识符均做字符校验,值一律走参数化占位符,防 SQL 注入;query/explain_query 为自由 SQL 入口,靠只读校验与单语句限制收窄(见上)

• delete_rows/update_rows 强制要求 where 条件

• explain_query 的 analyze=true 真实执行语句,仅允许 SELECT/WITH 开头并自动包裹事务回滚(序列推进、函数副作用不可回滚)

• DROP/TRUNCATE 等语句可通过 execute 执行,客户端请依赖 destructiveHint 注解做确认

• 请勿将 .env 提交到版本库

开发与构建

npm run build   # tsc 编译到 build/

源码结构:src/config.ts(配置)、src/db.ts(连接池与事务句柄)、src/sql.ts(SQL 构造与只读校验)、src/format.ts(结果格式化)、src/index.ts(MCP 服务器与工具注册)。

拿到真实 GaussDB 实例后:填写 .env → npm run build → node build/index.js 配合任意 MCP 客户端实测;或先单独验证连接:配置 env 后运行 test_connection 工具。