GaussDB Read-Only MCP

gaussdb-ro-mcp

[简体中文] | English

メモ

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 ドライバー （Huawei Cloud 公式のオープンソース 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 権限のみを付与したデータベースアカウントの使用を推奨します（下記参照）。これにより最小権限を実現します

提供する MCP ツール

ツール	機能
test_connection	接続テスト：サーバーバージョン、現在のデータベース／ユーザー、読み取り専用状態、遅延を確認します。instance パラメーターは任意です
list_schemas	スキーマ一覧：オブジェクト数、コメントを表示します。include_system でシステムスキーマを含めるかどうかを指定します
list_tables	テーブル／ビュー一覧：種類（テーブル／ビュー／マテリアライズドビュー／パーティションテーブル／外部テーブル）、推定行数、コメントを表示します。schema で絞り込めます
describe_table	テーブル構造：列（型／NULL 可否／デフォルト値／コメント）、主キーと制約、すべてのインデックスと定義を表示します。ビューの場合はビュー定義 SQL を返し、パーティションテーブルの場合はパーティション一覧（GaussDB pg_partition）を返します
execute_select	SELECT を実行します。単一の SELECT/WITH のみ受け付け、max_rows とタイムアウトで制限し、列名、行データ、切り詰めの有無を返します

すべてのツールは、データソースを選択するための任意の instance パラメーターを受け付けます。省略した場合は default_instance が使用されます。デフォルトであることを示す表示を含むすべてのインスタンス名は、このパラメーターのスキーマ説明に記載されるため、エージェントは試行錯誤せずにツール一覧を取得する段階で利用可能なインスタンスを確認できます。

類似プロジェクトとの比較

	gaussdb-ro-mcp（本プロジェクト）	GaussDB-MCP	Multi DB MCP	汎用 PostgreSQL MCP サーバー
対象	GaussDB 専用の読み取り専用調査	GaussDB のフル機能アクセス：クエリ、書き込み、トランザクション、診断・運用、ユーザー権限	17 種類のデータベース向け汎用コネクター（GaussDB/openGauss を含む）、MCP + REST API	PostgreSQL ネイティブ
GaussDB への対応	公式 Go ドライバー。集中型／プライマリ・スタンバイ構成／分散型に対応	公式 Node.js ドライバー（gaussdb-node）	PostgreSQL 汎用プロトコルを使用	pg_partition など、GaussDB 固有のシステムカタログには未対応
読み取り専用の保証	三層の多層防御：SQL 静的検証 + トランザクションレベルでの READ ONLY 強制 + 最小権限の推奨	読み取り専用モードなし（デフォルトの root 管理者アカウントで、設計上書き込みに対応）	アプリケーション層でデフォルト読み取り専用	プロジェクトごとに異なります
GaussDB 固有のメタデータ	パーティションテーブル（pg_partition）、外部テーブル、マテリアライズドビュー、ビュー定義 SQL、すべてのインデックス定義	一部対応	PG プロトコルに基づいて調査。一部対応	なし
実行時依存関係	なし（静的コンパイルされた単一バイナリで、オフラインデプロイ可能）	Node.js ≥ 20	Node.js（npx）	プロジェクトによって異なります
複数インスタンスの管理	設定ファイルで複数インスタンスを一元管理し、ツールの instance パラメーターで切り替え	単一インスタンス（環境変数）	単一接続（起動パラメーター）	通常は単一インスタンス
非 SSL のイントラネット環境	デフォルトは sslmode=disable	対応（デフォルトで SSL 無効）	対応	対応
ライセンス	Apache-2.0	未宣言	未宣言	プロジェクトによって異なります

各プロジェクトの対象は異なります。読み書きと運用のすべての機能が必要な場合は、フル機能のサーバーが適切な選択肢です。コーディングエージェントにデータを安全に調査させること（特に本番データベースの場合）が目的であれば、読み取り専用の制約と多層防御が本プロジェクトの価値です。 上記の情報は各プロジェクトの公開 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=<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。

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 静态校验 / 只读强制）的改动请附带回归测试