面向 Coding Agent（Claude Code、OpenCode 等）的 GaussDB 只读 MCP 服务器。基于
GaussDB 官方 Go 驱动
（华为云官方开源的 pgx v5 适配版，源码随仓库内置于 third_party/gaussdb-go，支持离线构建），
通过 stdio 传输提供数据库只读探查工具。
专为内网非 SSL 环境设计：默认 sslmode=disable，配置文件支持同时管理多个 GaussDB 实例。
层级 | 机制 | 说明 |
1. SQL 静态校验 |
| 仅放行单条 |
2. 事务级强制 |
| 所有查询统一在显式只读事务中执行： |
3. 部署建议 | README | 建议使用仅授予 |
Related MCP server: starrocks-mcp
工具 | 功能 |
| 连通性测试：服务器版本、当前库/用户、只读状态、延迟；可选 |
| schema（模式）清单：对象数、注释； |
| 表/视图清单：类型（表/视图/物化视图/分区表/外表）、估算行数、注释；可按 |
| 表结构：列（类型/可空/默认值/注释）、主键与约束、全部索引及定义；视图返回视图定义 SQL；分区表返回分区清单（GaussDB |
| 执行 SELECT：仅接受单条 SELECT/WITH，受 |
所有工具均接受可选 instance 参数以选择数据源，缺省使用 default_instance。
从 Releases 下载对应架构的二进制，
用 install 安装到 /usr/local/bin（其他架构或内网环境可自行构建，见下节）：
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要求 Go 1.26+（与 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复制 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方式一：项目根目录 .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.yamlopencode.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 静态校验 / 只读强制）的改动请附带回归测试
查看表/视图的完整结构：列清单（类型/可空/默认值/注释）、主键与约束、全部索引及其定义；视图返回视图定义 SQL，分区表返回分区清单。
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | 表名或视图名（必填） | |
| schema | No | 模式名，省略时自动在非系统模式中查找（歧义时报错） | |
| instance | No | 数据源名称（配置文件中 instance 的 name），省略时使用默认实例 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing output categories and special-case behavior: views return definition SQL and partitioned tables return a partition list. However, it does not explicitly state read-only semantics, error behavior for missing tables, or permission requirements, which would make it fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the core action and then lists all value-adding details without filler. Every clause earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a metadata inspection tool, the description covers the essential return categories and even anticipates special cases (views and partitioned tables). Since there is no output schema, the description partially compensates by describing content, but it omits error/ambiguity behavior and access considerations, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description itself adds little beyond what the schema already documents. The mention of table/view names roughly maps to the table parameter, but there is no additional semantic depth for schema resolution or instance selection beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (查看/inspect) and names the exact resource: the full structure of a table or view. It enumerates what is returned—columns with metadata, primary keys and constraints, indexes, view definition SQL, and partition lists—making its purpose unmistakable and clearly distinct from siblings like execute_select (row data) and list_tables (only table names).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given for when to use this tool versus alternatives. The intended use case is implied by the content, but the description never states exclusions or points to siblings such as execute_select for data retrieval or list_tables for name discovery, nor does it mention when the optional schema or instance parameters matter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
执行只读 SELECT 查询（唯一允许的 SQL 入口）。仅接受单条 SELECT/WITH 语句：禁止 DML/DDL、SELECT INTO、行锁、多语句与危险函数；查询在服务端强制的只读事务中执行。
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | 要执行的 SELECT 语句（必填），仅允许单条 SELECT/WITH 查询 | |
| instance | No | 数据源名称（配置文件中 instance 的 name），省略时使用默认实例 | |
| max_rows | No | 本次返回的最大行数，默认取实例配置，上限受服务端限制 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It states that queries execute inside a server-enforced read-only transactionccurately characterizes the tool's safety and constraint behavior. This goes well beyond a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense, front-loaded sentence that packs purpose, constraints, and transaction behavior without redundancy. Every clause adds value and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description is complete on safety and allowed usage, and max_rows implies row results. A slight gap is the absence of any explicit description of the return shape or error behavior, but this is minor for a tool whose main risk is safely constraining SQL execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with 100% description coverage, so the baseline is 3. The description reinforces the single-statement SELECT/WITH restriction but adds no new parameter-level detail beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes read-only SELECT queries and is the 'only allowed SQL entry,' which strongly identifies its purpose. It also differentiates itself from sibling metadata/connection tools such as describe_table and list_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: it is the only SQL entry point and only accepts single SELECT/WITH statements. It lists forbidden operations (DML/DDL, SELECT INTO, row locks, multi-statements, dangerous functions). It does not directly name sibling alternatives, but the constraints make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出 GaussDB 数据库中的 schema（模式）清单，含每个模式下的对象数量与注释。默认排除系统模式。
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | 数据源名称（配置文件中 instance 的 name），省略时使用默认实例 | |
| include_system | No | 是否包含系统模式（pg_catalog 等），默认 false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
无注释，描述承担行为披露责任。描述了默认排除系统模式这一行为，但未说明返回格式、是否只读、权限要求等。对于只读列表工具，信息基本足够但不够全面。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
一句话简洁地说明了工具功能，没有冗余，但未提供任何额外背景或使用提示，结构清晰但略显单薄。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
工具简单，参数少且 schema 覆盖完整，无输出 schema 要求。描述涵盖了核心功能，但未说明返回格式或典型使用场景，对简单工具而言基本够用。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema 覆盖 100%，instance 和 include_system 均有描述。描述中提及'默认排除系统模式'与 include_system 参数相关，但未增加超出 schema 的新信息，仅重复了默认值。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
描述明确说明列出 GaussDB 数据库中的 schema 清单，并提及包含对象数量和注释，动词'列出'和资源'schema'具体明确，与兄弟工具（list_tables、describe_table 等）容易区分。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
描述说明了默认行为（排除系统模式），但没有明确提及何时使用此工具而非其他兄弟工具，也未说明哪些场景不适合使用。缺少与 list_tables 等工具的对比或使用条件。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出 GaussDB 数据库中的表和视图清单（表名、类型、估算行数、注释）。可通过 schema 参数过滤到指定模式。
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | 限定模式名（schema），省略时扫描全部非系统模式 | |
| instance | No | 数据源名称（配置文件中 instance 的 name），省略时使用默认实例 | |
| include_system | No | 是否包含系统模式，默认 false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure. It provides a useful detail: by default it excludes system schemas (but can include them via the include_system parameter). It does not describe output format or potential performance implications (e.g., full scan of all schemas), which could be more transparent for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise - a single sentence with an additional sentence on the schema parameter. It is front-loaded with the core purpose. It could be slightly more structured (e.g., bullets) but is appropriately sized for the content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the tool is relatively simple (listing tables/views), the description covers the essential: what it returns, the schema filter, and the default exclusion of system schemas. It lacks explicit mention that this is a read-only operation, but the 'list' verb implies that. It might also mention that the return can be large, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all three parameters (schema, instance, include_system) are well described in the schema. The description adds value by mentioning the schema filter and the default behavior of scanning all non-system schemas, but it adds little beyond the schema for instance and include_system.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('列出' / list), a clear resource (tables and views in the GaussDB database), and the exact information returned (table name, type, estimated rows, comment). It is unambiguous and distinct from siblings like describe_table or execute_select, which are clearly different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the schema parameter for filtering, implying a use case of narrowing the query scope. It does not explicitly state when not to use this tool or mention alternatives, but the context (listing inventory) is clear enough. A small gap: no mention that describe_table should be used for single-table details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
测试 GaussDB 数据源连通性，返回服务器版本、当前数据库、用户、只读状态与连接耗时。不指定 instance 时测试默认实例。
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | 数据源名称（配置文件中 instance 的 name），省略时使用默认实例 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It states what the tool does (connectivity test), what it returns (server version, current database, user, read-only status, connection latency), and how the default instance is selected. It does not explicitly address side effects or auth requirements, but the described behavior is clearly informational and non-mutating, which is adequate context for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences: the first states purpose and expected output fields, and the second clarifies the optionality of the only parameter. Every sentence earns its place with no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, no nested objects, no output schema. The description covers the operation, the returned fields, and the default behavior. The only minor gap is that failure/error behavior when the connection cannot be established is not mentioned, but for a lightweight connectivity test this is not a blocking omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the instance parameter, including the default-instance behavior. The tool description repeats that behavior without adding new semantic detail such as value format, examples, or constraints. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: '测试 GaussDB 数据源连通性' (test GaussDB data source connectivity). It also lists concrete return values, and the tool is clearly distinct from the data-plane siblings (describe_table, list_tables, execute_select, list_schemas), so an agent can identify it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful invocation guidance for the instance parameter ('不指定 instance 时测试默认实例'), which tells the agent when the parameter can be omitted. However, it never states when to choose this tool over siblings, such as using it before running queries, nor does it give preconditions or exclusions. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.2describe_tableexecute_selectlist_schemaslist_tablestest_connectionScored across 5 tools
Each tool targets a distinct resource or action: listing schemas, listing tables, describing a specific table, executing read-only queries, and testing connectivity. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern in snake_case (describe_table, execute_select, list_schemas, list_tables, test_connection). The naming is uniform and predictable.
With 5 tools, the set is well-scoped for a read-only database exploration server. Each tool earns its place and the count is appropriate for the server's purpose.
The tool surface covers the full read-only workflow: discover schemas, list tables/views, inspect table structure, execute queries, and verify connectivity. No obvious gaps exist for the stated read-only domain.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Read-only MCP server for wafergraph.com's semiconductor & AI supply-chain data: 30 tools, no auth.
