The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gaussdb Ro MCP listing page.
面向 Coding Agent(Claude Code、OpenCode 等)的 GaussDB 只读 MCP 服务器。基于
GaussDB 官方 Go 驱动
(华为云官方开源的 pgx v5 适配版,源码随仓库内置于 third_party/gaussdb-go,支持离线构建),
通过 stdio 传输提供数据库只读探查工具。
专为内网非 SSL 环境设计:默认 sslmode=disable,配置文件支持同时管理多个 GaussDB 实例。
| 层级 | 机制 | 说明 |
|---|---|---|
| 1. SQL 静态校验 | internal/guard | 仅放行单条 SELECT/WITH 查询:拒绝 DML/DDL(含 CTE 内写语句)、SELECT ... INTO、FOR UPDATE/SHARE 行锁、多语句、危险函数(dblink*、set_config、setval、pg_read_file*、pg_terminate_backend、pg_advisory_*、大对象写等,可配置)。词法分析正确跳过字符串/注释/引号标识符,避免误报 |
| 2. 事务级强制 | internal/db | 所有查询统一在显式只读事务中执行:BEGIN → SET LOCAL TRANSACTION READ ONLY → 查询 → COMMIT(失败回滚)。GaussDB 分布式版仅支持事务级只读设置,该方式在集中式/主备与分布式实例上通用;另设 SET statement_timeout。即使第 1 层被绕过,服务端也会拒绝事务内一切写入(包括函数内部的写) |
| 3. 部署建议 | README | 建议使用仅授予 SELECT 权限的数据库账号(见下文),实现权限最小化 |
| 工具 | 功能 |
|---|---|
test_connection | 连通性测试:服务器版本、当前库/用户、只读状态、延迟;可选 instance 参数 |
list_schemas | schema(模式)清单:对象数、注释;include_system 控制是否含系统模式 |
list_tables | 表/视图清单:类型(表/视图/物化视图/分区表/外表)、估算行数、注释;可按 schema 过滤 |
describe_table | 表结构:列(类型/可空/默认值/注释)、主键与约束、全部索引及定义;视图返回视图定义 SQL;分区表返回分区清单(GaussDB pg_partition) |
execute_select | 执行 SELECT:仅接受单条 SELECT/WITH,受 max_rows/超时限制,返回列名+行数据+是否截断 |
所有工具均接受可选 instance 参数以选择数据源,缺省使用 default_instance。
从 Releases 下载对应平台的二进制
(linux-amd64 / linux-arm64 / darwin-arm64 / windows-amd64.exe;其他平台或内网环境可自行构建,见下节)。
Linux:
macOS(Apple Silicon):
Windows(PowerShell;放入 PATH 目录后即可直接调用):
各产物校验值见 Release 页的 SHA256SUMS.txt。
要求 Go 1.26+(与 go.mod 一致)。驱动源码已内置于 third_party/gaussdb-go(通过 replace 指令引用),
正常联网环境下 go build 会自动解析其余依赖;纯内网环境请先在有网环境执行 go mod vendor
后携带 vendor/ 目录,用 go build -mod=vendor 构建。
交叉编译其他平台(纯 Go,CGO_ENABLED=0 即可):CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -o ... ./cmd/gaussdb-ro-mcp。
复制 gaussdb-ro-mcp.example.yaml 为 gaussdb-ro-mcp.yaml 并修改。
配置文件查找顺序:-config 参数 > 环境变量 GAUSSDB_RO_MCP_CONFIG > ./gaussdb-ro-mcp.yaml。
方式一:项目根目录 .mcp.json(或 claude mcp add 命令):
opencode.json:
即使数据库账号被限定为只读,本服务的 SQL 校验与会话强制仍会拦截
锁行(FOR UPDATE)、SELECT INTO、危险函数调用、长查询等行为。
所有运行日志输出到 stderr(stdout 为 MCP 协议通道),包括配置加载、 数据源就绪、会话只读校验结果等,便于在代理客户端的 MCP 日志中排障。
可用 Docker 快速起一个 openGauss 测试实例并灌入测试数据:
集成测试覆盖:只读会话强制(服务端拒绝写入)、5 个工具的端到端行为、 真实二进制 stdio 子进程冒烟。注意:本驱动使用 GaussDB 扩展协议(3.51), 无法连接原生 PostgreSQL,集成测试需要真实的 GaussDB / openGauss 实例。
欢迎提交 Issue 和 Pull Request:
go vet ./... 与 go test ./... 通过;涉及安全防护逻辑(SQL 静态校验 / 只读强制)的改动请附带回归测试