YugabyteDB MCP Server

YugabyteDB MCP 服务

一个适用于 YugabyteDB 和 PostgreSQL 的 MCP 服务，可让大模型（Claude Desktop、Cursor、Windsurf 等）汇总架构、运行只读查询，并在可配置的防护规则层后执行写入语句。

功能

• summarize_database — 列出某个架构中的表、列和行数（只读）
• run_read_only_query — 在 BEGIN READ ONLY 下执行 SELECT；以 JSON 格式返回结果（只读）
• run_write_query — 执行 INSERT/UPDATE/DELETE/MERGE/TRUNCATE/DDL，并受防护规则黑名单限制（具有破坏性，默认禁用——使用 --enable-write-query 或 YB_MCP_ENABLE_WRITE_QUERY=true 启用）

纵深防御：写入工具标注了 destructiveHint: true，因此即使防护规则允许执行语句，Claude Desktop 也会在每次调用前显示确认提示。

可选支持 OAuth（AWS Cognito）以及针对可自托管远程部署的 Origin 标头验证。

先决条件

• Python 3.10+
• uv（推荐）或 pip
• 可连接的 YugabyteDB 或 PostgreSQL 数据库
• MCP 客户端（Claude Desktop、Cursor、Windsurf 等）

安装

有三种安装方式，大致按最终用户选择的可能性排序：

# uvx — no install at all; fetches and runs on demand. Handy for one-off use
# and also the form the MCPB Desktop extension uses internally.
uvx yugabytedb-mcp-server --help

# pipx — installs to an isolated venv, puts the script on $PATH.
pipx install yugabytedb-mcp-server

# uv tool — same idea, uv-managed.
uv tool install yugabytedb-mcp-server

# pip — system-level or current-venv install.
pip install yugabytedb-mcp-server

使用任意一种持久安装方式（pipx / uv tool / pip）后，请通过以下命令验证：

yugabytedb-mcp --help
# or, equivalently:
yugabytedb-mcp-server --help

两个控制台脚本均已注册，并指向同一个入口点—— yugabytedb-mcp 是简短形式，yugabytedb-mcp-server 与 软件包名称一致，也是 uvx 默认解析到的名称。

预发布版本说明：v2 处于发布候选阶段时（例如 2.0.0rc2）， 默认安装不会选中该版本。目前，请使用明确指定的版本安装 （pipx install yugabytedb-mcp-server==2.0.0rc2），或使用 --pip-args='--pre'。待发布 2.0.0 稳定版后，此限制便会消失。

如需从源代码进行开发，请参阅下文的开发。

配置

环境变量	CLI 标志	必需	说明
YUGABYTEDB_URL	--yugabytedb-url	是	libpq 连接字符串（例如 host=… port=5433 dbname=… user=… password=…）。
YB_MCP_TRANSPORT	--transport	否	stdio（默认）或 http。
YB_MCP_STATELESS_HTTP	--stateless-http	否	设为 true 可启用无状态 Streamable-HTTP——多副本可自托管部署时必需。
YB_MCP_REQUIRE_WHERE_ON_UPDATE	--require-where-on-update	否	拒绝不带 WHERE 子句的 UPDATE。默认值为 false。
YB_MCP_REQUIRE_WHERE_ON_DELETE	--require-where-on-delete	否	拒绝不带 WHERE 子句的 DELETE。默认值为 false。
YB_MCP_ENABLE_WRITE_QUERY	--enable-write-query	否	启用 run_write_query 工具。默认值为 false（写入工具已禁用）。
MCP_AUTH_PROVIDER	--mcp-auth-provider	否	cognito 或 oidc。留空则禁用身份验证。完整的 OIDC/Cognito 设置及按用户进行的身份映射说明见 OIDC.md。
MCP_HOST	--host	否	HTTP 传输的绑定主机。默认值为 127.0.0.1（环回地址）。设为 0.0.0.0 可在所有网络接口上开放——此时必须启用身份验证（参见 MCP_AUTH_PROVIDER）。
MCP_BASE_URL	—	启用身份验证时	服务可访问的公共基础 URL（例如 https://mcp.example.com）。
MCP_ALLOWED_ORIGINS	—	否	以逗号分隔的 Origin 值允许列表，用于防御 DNS 重绑定。区分大小写（RFC 6454）。默认值为 MCP_BASE_URL。
MCP_ALLOW_UNAUTHENTICATED	—	否	允许在非环回主机上以无身份验证模式运行 HTTP 的应急选项。仅供开发使用；启动日志会显示醒目的 WARNING。
YB_LOG_LEVEL	—	否	yugabytedb-mcp 日志记录器系列的日志级别（默认值为 INFO）。
YB_AWS_SSL_ROOT_CERT_SECRET_ARN	--yb-aws-ssl-root-cert-secret-arn	否	存储 YugabyteDB TLS 根证书的 AWS Secrets Manager 密钥的 ARN。
YB_AWS_SSL_ROOT_CERT_KEY	--yb-aws-ssl-root-cert-key	否	密钥存储多个证书时使用的 JSON 键。
YB_AWS_SSL_ROOT_CERT_SECRET_REGION	--yb-aws-ssl-root-cert-secret-region	否	密钥所在的 AWS 区域。
YB_SSL_ROOT_CERT_PATH	--yb-ssl-root-cert-path	否	写入获取到的证书的位置。默认值为 /tmp/yb-root.crt。

关于 OIDC/Cognito 身份验证、按用户进行的 SET ROLE 映射、身份映射文件格式以及 /auth/login 快捷方式，请参阅 OIDC.md。

.env.example 中提供了入门模板。

快速开始 — Claude Desktop

有两种接入方式。第一种使用 uvx，完全无需安装——只需 uv。第二种假设你已运行 pipx install（或同类命令），并且 yugabytedb-mcp 脚本位于 $PATH 中。

选项 1 — 使用 uvx（无需安装）：

{
  "mcpServers": {
    "yugabytedb": {
      "command": "uvx",
      "args": ["yugabytedb-mcp-server"],
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

选项 2 — 使用已安装的脚本：

运行 pipx install yugabytedb-mcp-server（或 uv tool install …）后：

{
  "mcpServers": {
    "yugabytedb": {
      "command": "yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

claude_desktop_config.json 的位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

重启 Claude Desktop。三个工具将显示其标题和提示徽章（只读工具带有只读图标；每次调用 run_write_query 前都会出现确认提示）。

目前唯一发布的版本是 2.0.0rc2，因此 uvx 片段的 args 中需要包含 ["[email protected]"]（或 ["--pre", "yugabytedb-mcp-server"]）。待稳定版 2.0.0 发布后，即可移除显式版本号。

其他 MCP 客户端

同样的方法也适用于 Cursor（Settings → MCP → Add a new global MCP server）和 Windsurf（Settings → Cascade → MCP Servers → Add custom server）——使用上文的 uvx 形式或已安装脚本形式均可。

针对 HTTP 模式服务使用 MCP Inspector：

YUGABYTEDB_URL="…" yugabytedb-mcp --transport http
# in another shell:
npx @modelcontextprotocol/inspector
# In the GUI: URL http://localhost:8000/mcp, transport Streamable-HTTP

工具

工具	标题	提示	功能说明
summarize_database(schema='public')	"Summarize database schema and row counts"	readOnlyHint: true	列出 schema 中的表、列和行数
run_read_only_query(query)	"Run a read-only SQL query"	readOnlyHint: true	将查询包装在 BEGIN READ ONLY 中，并以 JSON 格式返回行
run_write_query(query)	"Run a write SQL query (with guardrails)"	destructiveHint: true	根据防护规则黑名单验证查询，然后执行。默认禁用——需要 --enable-write-query。

run_write_query 的防护规则

以下语句类别会在执行前被拒绝：

• DROP DATABASE/SCHEMA、ALTER DATABASE、CREATE DATABASE
• 角色/权限操作：GRANT、REVOKE、CREATE/ALTER/DROP ROLE、CREATE/ALTER/DROP USER
• 可在所有者权限下运行的存储代码（SECURITY DEFINER）：CREATE FUNCTION、CREATE PROCEDURE、ALTER FUNCTION、ALTER PROCEDURE
• 文件系统/代码执行：COPY TO/FROM、LOAD、匿名 DO $$ … $$、CREATE EXTENSION
• 服务端配置：ALTER SYSTEM、RESET ALL
• 危险的内置函数：pg_sleep、pg_read_file、pg_write_file、lo_import、lo_export、dblink
• 架构隔离：SET search_path、CREATE SCHEMA
• 多语句查询（包含分隔符分号的任何查询）
• psql 元命令（\c、\d、\!）
• 可选：不带 WHERE 子句的 UPDATE / DELETE

INSERT / UPDATE / DELETE / DDL 的运行时长受 YB_MCP_STATEMENT_TIMEOUT_MS 限制（每次写入都会应用 SET LOCAL statement_timeout）——失控的 INSERT … SELECT 或宽泛的 INSERT … VALUES 会由数据库终止，而非通过静态行数上限限制。

CREATE TABLE … AS SELECT 和 SELECT … INTO 在结构上类似于不受限制的行复制，但有意允许使用——这是从查询生成快照的常见方式。

此列表尽力而为，并非详尽无遗。destructiveHint: true 是第二道防线。

自托管远程模式

对于多用户或共享部署，请将服务作为 Streamable HTTP 服务运行在 TLS 反向代理之后，并通过 Cognito OAuth（或通用 OIDC）控制访问权限。完整配置说明——包括提供方配置、每用户的 SET ROLE 映射、身份映射文件格式、/auth/login 快捷方式和安全指南——请参阅 OIDC.md。

默认安全： 修复后，HTTP 模式默认绑定到 127.0.0.1，并且在以下两项同时成立时拒绝启动：

• 绑定主机不是环回地址（MCP_HOST 设置为 0.0.0.0 或某个特定地址）
• 未配置身份验证提供方（未设置 MCP_AUTH_PROVIDER）

对于共享/联网部署，请同时设置 MCP_HOST=0.0.0.0 和 MCP_AUTH_PROVIDER：

export MCP_HOST=0.0.0.0                # expose beyond loopback (default: 127.0.0.1)
export MCP_AUTH_PROVIDER=cognito
export MCP_BASE_URL=https://mcp.example.com
export COGNITO_USER_POOL_ID=us-west-2_XXXXXXXX
export COGNITO_AWS_REGION=us-west-2
export COGNITO_CLIENT_ID=…
export COGNITO_CLIENT_SECRET=…
export YUGABYTEDB_URL=…
export MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://claude.ai

yugabytedb-mcp --transport http --stateless-http

对于仅限开发且未进行身份验证的 0.0.0.0 使用场景，请设置 MCP_ALLOW_UNAUTHENTICATED=true——服务启动时会显示醒目的 WARNING。请勿在生产环境中使用此设置。

行为：

• 不带有效 Bearer 令牌的 /mcp 请求会返回 401。
• 带有不允许的 Origin 标头的请求会返回 403（防御 DNS 重绑定攻击）。
• /ping 无需身份验证，适用于存活探针。
• /auth/login 提供 Cognito 邮箱+密码 → 令牌快捷方式（详情请参阅 OIDC.md）。
• 多副本部署必须使用 --stateless-http——否则 MCP 会话状态会保存在进程内存中，循环负载均衡会导致会话中断。

用于 TLS 证书的 AWS Secrets Manager

如果数据库 TLS 根证书存储在 AWS Secrets Manager 中，服务可以自动获取并使用它。支持纯文本 PEM，也支持带 JSON 键的证书包（设置 YB_AWS_SSL_ROOT_CERT_KEY 以选取其中一项）。

yugabytedb-mcp \
  --yugabytedb-url "host=… port=5433 dbname=… user=… password=… sslmode=verify-full" \
  --yb-aws-ssl-root-cert-secret-arn arn:aws:secretsmanager:us-east-1:…:secret:my-cert \
  --yb-aws-ssl-root-cert-secret-region us-east-1

Docker

docker build -t mcp/yugabytedb .
docker run -p 8000:8000 -e YUGABYTEDB_URL="…" mcp/yugabytedb yugabytedb-mcp --transport http

安全

• 所有 SQL 均通过参数化查询执行；绝不会将用户输入插入语句字符串。
• 写入工具默认禁用——必须通过 --enable-write-query 显式启用。
• 写入工具的防护列表（见上文）会拦截风险最高的语句类别。
• destructiveHint: true 可确保 Claude Desktop 在执行写入操作时针对每次调用显示确认提示。
• 启用 OIDC 身份验证时，针对每位用户执行的 SET ROLE 会按调用方强制实施数据库级权限边界。角色名称使用 psycopg.sql.Identifier 安全引用。
• 配置 MCP_AUTH_PROVIDER 后，HTTP 传输要求提供有效的 Bearer 令牌。
• HTTP 传输会根据 MCP_ALLOWED_ORIGINS 验证 Origin 标头（默认为 MCP_BASE_URL）。
• HTTPS 由操作人员负责——请在服务前方的反向代理（nginx、ALB 等）处终止 TLS。
• 请使用遵循最小权限原则的数据库角色运行（仅部署 run_read_only_query 时使用只读角色；其他情况下使用权限限定于目标架构的角色，不要使用超级用户）。

请将安全问题私下报告至 [email protected]——请勿为漏洞公开提交 GitHub 问题。

隐私政策

适用 Yugabyte 的隐私政策：https://www.yugabyte.com/privacy-policy/

此 MCP 服务不会传输遥测数据。所有数据库访问都通过你提供的连接字符串，在 Claude（你的 MCP 客户端）与 YugabyteDB 实例之间进行。服务仅在本地向 stderr 写入日志（由 YB_LOG_LEVEL 控制）——没有内置远程日志聚合功能。

开发

git clone [email protected]:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync
uv run yugabytedb-mcp --help

注意：现在已无法直接运行 src/server.py。为适配 PyPI 分发（入口点 + 命名空间），包布局已重新组织，因此模块现在位于 src/yugabytedb_mcp_server/ 下。请始终通过 yugabytedb-mcp 控制台脚本调用（由 uv sync / pip install 注册）——使用 python 运行模块文件会跳过包导入机制，导致相对导入出错。

等效命令：

uv run yugabytedb-mcp                 # uses the console script
uv run python -m yugabytedb_mcp_server # uses the __main__.py shim

在 Claude Desktop 中本地测试连接器

根据你希望多大程度贴近生产安装体验，有两种方式：

最快——无需构建 MCPB，只需让 Claude Desktop 指向本地入口点。执行 uv sync 后，yugabytedb-mcp 脚本会位于 $PATH 中（通过当前激活的虚拟环境）。将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "yugabytedb-dev": {
      "command": "/absolute/path/to/repo/.venv/bin/yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=localhost port=5433 dbname=yugabyte user=yugabyte password=yugabyte",
        "YB_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

重启 Claude Desktop。使用 ~/Library/Logs/Claude/mcp-server-yugabytedb-dev.log（macOS）查看调试输出。此方式完全跳过 MCPB 打包，是迭代工具代码的理想流程。

更贴近生产——构建 .mcpb 并将其拖入 Claude Desktop。需要安装 MCPB CLI：

npm install -g @modelcontextprotocol/mcpb-cli   # one-time
mcpb validate manifest.json                      # static check
mcpb pack .                                      # produces yugabytedb-mcp-server-<version>.mcpb

将生成的 .mcpb 拖入 Claude Desktop——连接器安装程序界面会接手处理，并提示输入 manifest.json 中定义的 user_config 值。.mcpb 方式最接近审核人员实际体验的流程。注意：清单中的 mcp_config 会运行 uvx yugabytedb-mcp-server，首次启动时会从 PyPI 获取软件包。分享此捆绑包前，请确保其中引用的版本已发布。

测试

# unit tests (no DB, no network)
uv run pytest tests/test_guardrails.py tests/test_auth.py tests/test_identity_mapping.py

# integration tests (require a reachable Postgres-compatible DB)
YUGABYTEDB_URL="host=… port=… …" uv run pytest tests/

有关覆盖率表和手动 Cognito 冒烟测试步骤，请参阅 tests/README.md。

故障排除

• Claude Desktop 中出现 spawn yugabytedb-mcp ENOENT → 确保安装目录位于 Claude Desktop 可见的 PATH 中；运行 pipx ensurepath，或将入口点符号链接到 /usr/local/bin。
• MCP 客户端中的工具列表为空 → 重启客户端；检查 YB_LOG_LEVEL=DEBUG 输出，查看生命周期期间是否出现连接错误。
• 在包含多个副本的 HTTP+OAuth 模式下出现 "Invalid or expired transaction" / "Client Not Registered" → 请参阅可自托管的远程服务部分；多副本部署必须使用 --stateless-http。

许可证

Apache 许可证 2.0。