GaussDB Read-Only MCP

gaussdb-ro-mcp

[简体中文] | English

[!NOTE]

English: A read-only MCP server for Huawei GaussDB (centralized & distributed), built for

coding agents (Claude Code, OpenCode, etc.). Three layers of read-only enforcement — static SQL

validation, server-side READ ONLY transactions, and least-privilege account guidance — in a

single static binary designed for non-SSL intranet environments. Full documentation:

README_en.md.

面向 Coding Agent（Claude Code、OpenCode 等）的 GaussDB 只读 MCP 服务器。基于 GaussDB 官方 Go 驱动 （华为云官方开源的 pgx v5 适配版，源码随仓库内置于 third_party/gaussdb-go，支持离线构建）， 通过 stdio 传输提供数据库只读探查工具。

专为内网非 SSL 环境设计：默认 sslmode=disable，配置文件支持同时管理多个 GaussDB 实例。

只读保障（三层纵深防御）

提供的 MCP 工具

所有工具均接受可选 instance 参数以选择数据源，缺省使用 default_instance。全部实例名（含默认标注）会写入该参数的 schema 描述，agent 在获取工具列表阶段即可发现可选实例，无需试错。

与同类项目对比

各项目定位不同：需要完整读写与运维能力时，全功能服务器是合理选择；如果目标是让 Coding Agent 安全地探查数据（尤其在生产库上），只读约束与纵深防御是本项目的价值所在。 以上信息基于各项目公开 README 整理（2026-10），如有出入欢迎 提 Issue 指正。

安装

macOS / Linux（Homebrew）：

brew install gxc/tap/gaussdb-ro-mcp

gaussdb-ro-mcp --version

从 Releases 下载对应平台的二进制 （linux-amd64 / linux-arm64 / darwin-arm64 / windows-amd64.exe；其他平台或内网环境可自行构建，见下节）。

Linux：

curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-linux-amd64

sudo install -Dm 755 gaussdb-ro-mcp-linux-amd64 /usr/local/bin/gaussdb-ro-mcp gaussdb-ro-mcp --version

macOS（Apple Silicon）：

curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-darwin-arm64

sudo install -Dm 755 gaussdb-ro-mcp-darwin-arm64 /usr/local/bin/gaussdb-ro-mcp gaussdb-ro-mcp --version

Windows（PowerShell；放入 PATH 目录后即可直接调用）：

Invoke-WebRequest -Uri "https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-windows-amd64.exe" -OutFile "gaussdb-ro-mcp.exe"

Move-Item .\gaussdb-ro-mcp.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\" # 该目录默认在 PATH 中 gaussdb-ro-mcp --version

各产物校验值见 Release 页的 SHA256SUMS.txt。

构建

要求 Go 1.26.10+（与 go.mod 一致）。驱动源码已内置于 third_party/gaussdb-go（通过 replace 指令引用）， 正常联网环境下 go build 会自动解析其余依赖；纯内网环境请先在有网环境执行 go mod vendor 后携带 vendor/ 目录，用 go build -mod=vendor 构建。

go build -o gaussdb-ro-mcp ./cmd/gaussdb-ro-mcp

sudo install -Dm 755 gaussdb-ro-mcp /usr/local/bin/gaussdb-ro-mcp gaussdb-ro-mcp --version

交叉编译其他平台（纯 Go，CGO_ENABLED=0 即可）：CGO_ENABLED=0 GOOS= GOARCH= 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。

server:

max_rows: 500 # execute_select 默认行数上限 max_rows_cap: 10000 # 单次调用可放宽的硬上限 statement_timeout: 30s connect_timeout: 10s

instances:

• name: prod # 实例名称，工具调用时用 instance 参数引用 host: 192.168.0.10 port: 8000 database: postgres user: readonly_user password: "****" sslmode: disable # 内网非 SSL 默认值
• name: dev dsn: "gaussdb://readonly_user:****@192.168.1.20:5432/appdb?sslmode=disable"

default_instance: prod

接入 Coding Agent

Claude Code

方式一：项目根目录 .mcp.json（或 claude mcp add 命令）：

{

"mcpServers": { "gaussdb-readonly": { "command": "/usr/local/bin/gaussdb-ro-mcp", "args": ["-config", "/path/to/gaussdb-ro-mcp.yaml"] } } }

claude mcp add gaussdb-readonly -- /usr/local/bin/gaussdb-ro-mcp -config /path/to/gaussdb-ro-mcp.yaml

OpenCode

opencode.json：

{

"$schema": "https://opencode.ai/config.json", "mcp": { "gaussdb-readonly": { "type": "local", "command": ["/usr/local/bin/gaussdb-ro-mcp", "-config", "/path/to/gaussdb-ro-mcp.yaml"] } } }

数据库侧只读账号（强烈建议）

CREATE USER readonly_user WITH PASSWORD 'your-strong-password';

GRANT USAGE ON SCHEMA public TO readonly_user; GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user; -- 其他模式按需逐个授权

即使数据库账号被限定为只读，本服务的 SQL 校验与会话强制仍会拦截 锁行（FOR UPDATE）、SELECT INTO、危险函数调用、长查询等行为。

日志

所有运行日志输出到 stderr（stdout 为 MCP 协议通道），包括配置加载、 数据源就绪、会话只读校验结果等，便于在代理客户端的 MCP 日志中排障。

开发与测试

go test ./...                       # 单元测试（SQL 校验、配置解析）

GAUSSDB_RO_MCP_TEST_DSN="host=... port=... user=... password=... dbname=... sslmode=disable" \ go test -count=1 ./... # 集成测试（需 GaussDB/openGauss 实例）

可用 Docker 快速起一个 openGauss 测试实例并灌入测试数据：

docker run -d --name opengauss-ro-test -e GS_PASSWORD='Gaussdb@123' \

-p 127.0.0.1:15433:5432 --privileged docker.m.daocloud.io/enmotech/opengauss:latest

go run ./scripts/devseed "host=127.0.0.1 port=15433 user=gaussdb password=Gaussdb@123 dbname=postgres sslmode=disable"

集成测试覆盖：只读会话强制（服务端拒绝写入）、5 个工具的端到端行为、 真实二进制 stdio 子进程冒烟。注意：本驱动使用 GaussDB 扩展协议（3.51）， 无法连接原生 PostgreSQL，集成测试需要真实的 GaussDB / openGauss 实例。

目录结构

cmd/gaussdb-ro-mcp/     程序入口（stdio MCP 服务器）

internal/config/ YAML 配置：多实例数据源、行数/超时等 internal/guard/ 第 1 层防护：SQL 只读静态校验器 internal/db/ 多实例连接池 + 第 2 层防护：会话级 READ ONLY 强制、元数据查询 internal/tools/ MCP 工具注册与实现 scripts/devseed/ 集成测试数据灌入工具（开发用） third_party/gaussdb-go/ GaussDB 官方 Go 驱动源码（go.mod replace 引用）

反馈与贡献

欢迎提交 Issue 和 Pull Request：

• 问题反馈 / 功能建议：https://github.com/gxc/gaussdb-ro-mcp/issues
• 获取最新版本：https://github.com/gxc/gaussdb-ro-mcp/releases/latest
• 提交 PR 前，请确保 go vet ./... 与 go test ./... 通过；涉及安全防护逻辑（SQL 静态校验 / 只读强制）的改动请附带回归测试