MCPg : Production Grade Postgresql Mcp Server

MCPg

**面向 PostgreSQL 的生产级 Model Context Protocol 服务。**它让 AI Agent 能够安全地检查、查询、操作和调优 Postgres 数据库——提供 279 种工具，涵盖目录内省、 查询智能、自然语言 SQL、结构差异、混合搜索、 图查询、数据迁移、实时运维等。

**立即体验：**将 MCP 客户端或 MCP Inspector 指向托管的只读演示端点 https://devopam-mcpg-demo.hf.space/mcp。它使用临时演示数据提供只读工具；如需实际使用，请在自己的数据库旁运行 MCPg（参见快速开始）。

📍 收录于

• Official MCP Registry
• mcp.so
• mcpservers.org
• Smithery
• Glama
• MCP ServerList

---

方面	MCPg
安全性	默认只读 + AST 验证
传输方式	stdio + HTTP/SSE
安装	pip install mcpg
Postgres 版本	14–19
核心优势	生产可观测性 + 多租户

为什么选择 MCPg

• 默认安全。 只读访问模式。每条用户提供的 SQL 语句都会在执行前通过经过验证的 AST 允许列表进行解析。 传递给 PostgreSQL 作为 SQL 标识符的名称会使用带界定符的标识符引号编码（参见标识符策略）， 不会仅仅因为包含连字符或其他合法字符而遭到拒绝。 DDL、shell 和 LISTEN/NOTIFY 等功能默认关闭，需主动启用。每个工具都会发布 MCP ToolAnnotations（readOnlyHint、 openWorldHint），并根据同一套权限规则生成，让客户端无需猜测即可自动批准读取操作并对写入操作进行限制。
• 一个服务，覆盖广泛场景。 在单个 MCP 服务中提供应用数据访问（查询、搜索、游标、NL→SQL）以及 DBA 级操作（健康检查、索引调优、EXPLAIN 分析、锁、清理、转储、只读副本、迁移）。Agent 无需切换工具即可切换任务。
• 全面采用 PostgreSQL 原生能力。 不使用 ORM，没有抽象层开销——直接使用 psycopg3，支持所有 pg_* 系统视图，并在可用时集成 TimescaleDB、pgvector、PostGIS、Apache AGE 和 pg_stat_statements；不可用时也能平稳降级。
• 面向生产，而非演示。 连接池、按请求执行 SET ROLE 的多租户支持、带有降级主机检测的只读副本路由、使用专用连接的服务端游标、 速率限制、带正则表达式脱敏的审计跟踪、启动时强制启用 PG TLS、OIDC JWT Bearer 身份验证、按会话设置的语句／锁超时。
• 内置可观测性。 HTTP 传输上的 Prometheus /metrics 端点提供 mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds。每次工具调用都会记录结构化审计事件，参数中的凭据会被脱敏。
• 测试驱动，支持多个版本。 超过 2,500 个单元测试，以及一个在 CI 中针对真实 PostgreSQL 容器运行的集成测试套件——每次推送都会针对 PG 14、15、16、17、18 执行矩阵测试，另将 PG 19（beta） 作为实验性（非阻塞）条目进行跟踪，详见 issue #120。

---

安装

从 PyPI 安装（推荐）

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

验证：

mcpg --version

Docker

从 GitHub Container Registry 拉取预构建镜像（每次带标签的版本发布时都会发布——:latest 指向最新版本，也可以固定到某个版本，例如 :0.6.5）：

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

在 Windows PowerShell 中，将末尾的 \ 替换为反引号 `（或将命令写在一行）；安装指南提供了可直接复制的 Linux/macOS、PowerShell 和命令提示符命令块。

也可以从源代码自行构建：

docker build -t mcpg https://github.com/devopam/MCPg.git

多阶段镜像：运行时阶段会移除构建工具链，以 uid=10001 / gid=10001 身份运行，并使用 nologin shell；应用文件归 root 所有，且运行时用户只读。

从源代码安装（开发者）

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync 会创建包含所有运行时和开发依赖项的虚拟环境，并提供 mcpg 控制台脚本。

更多详情请参阅安装指南。

---

快速开始

一键安装： — 在集成指南中查看 Windsurf、JetBrains、Zed、Cline、Antigravity、Qwen Code、Perplexity、ChatGPT、Copilot Studio、Continue 和 HTTP 客户端的配置方法。

在 Claude Desktop 中一键安装（.mcpb）

从最新版本下载 mcpg-<version>.mcpb，然后双击（或将其拖入 Claude Desktop 的“设置”→“扩展”）。系统会提示你输入 PostgreSQL 连接 URL（该 URL 会存储在操作系统密钥链中），并选择访问模式（默认为只读）。安装就这么简单：安装包约为 2 kB，宿主会从 PyPI 获取适用于你平台的固定版本 mcpg。

或手动配置（stdio 传输）

将以下内容放入 claude_desktop_config.json（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json； Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

重启 Claude Desktop。现在，模型即可使用 MCPg 工具集。 你可以向 Claude 提出这样的问题：

“这个数据库中有哪些架构？请列出每个架构中最大的三张表并做总结。”

“这个查询为什么这么慢？ SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC”

还没有有趣的数据？填充演示数据集

MCPG_DATABASE_URL=postgresql://... mcpg --demo

只需运行一条命令，就能将一个经过精心整理的小型电商数据集（3,000 笔订单、900 条商品评论，以及特意植入的缺陷）填充到 mcpg_demo 架构中。该数据集经过设计，可让索引顾问、查询计划分析、全文搜索、PII 审计和图投影在你首次尝试时都能找到实际内容。查看引导式演示了解完整演示，也可随时运行 mcpg --demo-drop 将其删除。

作为 HTTP 服务运行（用于 IDE 集成、Web 应用等）

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

然后，让任何支持 MCP 的客户端连接到 http://localhost:8000/mcp（SSE 传输则连接 /sse）。HTTP 传输必须通过身份验证才能启动——设置 MCPG_HTTP_AUTH_TOKEN=... 使用静态 bearer 令牌，或设置 MCPG_AUTH_MODE=oidc，针对 OIDC 发行方执行完整的 JWT 验证。若要有意在不启用身份验证的情况下运行（不推荐），请设置 MCPG_HTTP_ALLOW_UNAUTHENTICATED=true。

---

配置

MCPg 完全通过环境变量配置——没有配置文件，也没有标志（CLI 的 --version / --demo / --demo-drop 是一次性命令，不属于配置）。唯一必需的变量是 MCPG_DATABASE_URL；其他变量都有安全的默认值。

常见场景

场景	设置
本地探索，只读	MCPG_DATABASE_URL
应用数据读写访问	MCPG_ACCESS_MODE=restricted
DBA 工具包（DDL、vacuum 等）	MCPG_ACCESS_MODE=unrestricted + MCPG_ALLOW_DDL=true
使用 bearer 身份验证的 HTTP 传输	MCPG_TRANSPORT=streamable-http + MCPG_HTTP_AUTH_TOKEN=…
多租户 SaaS	MCPG_DEFAULT_ROLE=tenant_a + MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…
读副本扇出	MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require
自然语言→SQL——单个提供商	设置任意一个厂商密钥（ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、XAI_API_KEY、GROQ_API_KEY、HF_TOKEN，等等——内置 22 个提供商）。MCPg 会自动选择默认项。
自然语言→SQL——多个提供商，由调用方选择	设置所有要启用的厂商密钥。每次调用 translate_nl_to_sql 时，都可以传入 provider="…"（任意已配置的内置或自定义提供商）。

完整参考

核心

变量	默认值	说明
MCPG_DATABASE_URL	必需	主 PostgreSQL DSN。支持 URI（postgresql://…）和关键字（host=… user=…）格式。远程主机需要 sslmode=require（或更严格的设置）。
MCPG_ACCESS_MODE	read-only	read-only | restricted（允许写入工具）| unrestricted（与门控变量搭配时也会解锁 DBA 工具）。
MCPG_TRANSPORT	stdio	stdio（默认，用于 Claude Desktop）| streamable-http | sse。
MCPG_LOG_LEVEL	INFO	DEBUG | INFO | WARNING | ERROR | CRITICAL。
MCPG_HTTP_HOST	127.0.0.1	HTTP 传输的绑定地址。在容器内设置为 0.0.0.0。
MCPG_HTTP_PORT	8000	HTTP 传输的监听端口（1–65535）。

能力门控（选择启用影响范围更大的工具）

变量	默认值	说明
MCPG_ALLOW_DDL	false	暴露 DDL 工具（run_ddl、create_graph、drop_graph、hypertable 工具、迁移工具）。需要 MCPG_ACCESS_MODE=unrestricted。
MCPG_ALLOW_SHELL	false	暴露由子进程支持的工具（dump_database、restore_database、run_pg_binary）。所需的 PG 客户端二进制文件必须位于 PATH 中。
MCPG_ALLOW_TIMESCALEDB_ADMIN	false	在 unrestricted 模式下，搭配 MCPG_ALLOW_DDL 可暴露具有破坏性或开销较大的 TimescaleDB 工具（drop_chunks、compress_chunk、decompress_chunk、reorder_chunk、merge_chunks、refresh_continuous_aggregate、run_job、alter_job、delete_job）；每项都需要先执行 dry_run，再设置 confirm=true + confirmation_token。参见 docs/timescaledb.md。
MCPG_ALLOW_ALTER_SYSTEM	false	暴露 alter_system、alter_system_reset_all、reload_config（仅限 unrestricted 模式；采用两步 confirm=true 流程——参见 docs/alter-system.md）。MCPG_ALTER_SYSTEM_ALLOWLIST / MCPG_ALTER_SYSTEM_DENYLIST（以逗号分隔的 GUC 名称）可缩小或扩展内置拒绝列表。
MCPG_ALLOW_LISTEN	false	暴露 LISTEN/NOTIFY 工具（subscribe_channel、poll_notifications、unsubscribe_channel、list_notification_subscriptions）。

身份验证（仅限 HTTP 传输）

变量	默认值	描述
MCPG_AUTH_MODE	static	static（将 bearer 与 MCPG_HTTP_AUTH_TOKEN 比较）| oidc（完整 JWT 验证）。
MCPG_HTTP_AUTH_TOKEN	—	当 MCPG_AUTH_MODE=static 时必需的 bearer 令牌。使用恒定时间比较。除非设置此项、MCPG_AUTH_MODE=oidc 或 MCPG_HTTP_ALLOW_UNAUTHENTICATED=true，否则 HTTP 传输将拒绝启动（ConfigError）。
MCPG_HTTP_ALLOW_UNAUTHENTICATED	false	显式绕过 HTTP 传输的失败时默认拒绝身份验证检查。设置后，每次启动都会发出醒目日志；不建议使用。
MCPG_OIDC_ISSUER	—	OIDC 颁发者 URL（当 MCPG_AUTH_MODE=oidc 时必需）。
MCPG_OIDC_AUDIENCE	—	预期的 aud 声明（当 MCPG_AUTH_MODE=oidc 时必需）。
MCPG_OIDC_JWKS_URL	自动发现	覆盖 JWKS 端点（否则从颁发者的 .well-known 自动发现）。
MCPG_OIDC_ROLE_CLAIM	—	JWT 声明，其值将成为每个请求的 PG 角色（SET LOCAL ROLE）。可与多租户驱动程序配合使用。

HTTP 加固（仅限 HTTP 传输）

变量	默认值	描述
MCPG_HTTP_MAX_BODY_BYTES	1048576	（1 MiB）超过此大小的请求正文将返回 413。按流式传输的字节数计数，因此缺失或虚报的 Content-Length 无法绕过此限制。
MCPG_HTTP_ALLOWED_ORIGINS	—	以逗号分隔的 CORS 允许列表。未设置 = 不启用 CORS 中间件（不发送跨域标头）。
MCPG_HTTP_HSTS_MAX_AGE	63072000	Strict-Transport-Security 的 max-age（2 年，OWASP 当前建议值）。设为 0 可禁用 HSTS 标头。除非应用已设置安全标头，否则始终会添加安全标头（CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy）。
MCPG_HTTP_REQUEST_TIMEOUT_SECONDS	0	每个请求的墙钟时间上限（超时后返回 504）。0 = 禁用。如果依赖长连接 SSE / streamable-http 流，请保持禁用 — 硬性上限也会切断这些连接。
MCPG_HTTP_TRUSTED_HOSTS	—	以逗号分隔的允许 Host 标头值列表（支持 *.example.com 这类通配符）。未设置 = 不验证 Host 标头（当前行为）。设置后，Host 不匹配的请求将通过 Starlette 的 TrustedHostMiddleware 返回 400。

多租户（SET ROLE）

变量	默认值	描述
MCPG_DEFAULT_ROLE	—	应用于每个查询的静态 PG 角色。会验证标识符。
MCPG_ALLOWED_ROLES	—	以逗号分隔的允许列表。设置后，X-MCPG-Role 标头 / OIDC 角色声明必须属于此列表。

只读副本

变量	默认值	描述
MCPG_REPLICA_URLS	—	以逗号分隔的副本 DSN。force_readonly 查询会在健康副本之间轮询；发生故障时回退到主库；降级副本的重试窗口为 30 s。

多个数据库（只读次级数据库）

变量	默认值	描述
MCPG_SECONDARY_DATABASE_URLS	—	以逗号或换行分隔的 name=dsn 条目，用于指定此服务可访问的其他只读数据库（例如 analytics=postgresql://…?sslmode=require,reporting=postgresql://…?sslmode=require）。支持读取的工具接受可选的 database 参数，用于按名称选择次级数据库；省略则使用主数据库。次级数据库为只读 — 由 PostgreSQL 强制执行（每个查询都在 READ ONLY 事务中运行），因此写入 / DDL / shell / migrate 操作始终针对主数据库。名称必须是简单标识符（[a-z0-9_]+）、彼此唯一，且不能为 primary（MCPG_DATABASE_URL 的保留 ID）。TLS 规则与主 DSN 相同。调用 list_databases 可查看已配置的 ID 及其可连接状态。

连接池 / 超时 / TLS

变量	默认值	描述
MCPG_POOL_MIN_SIZE	1	连接池的最小连接数。
MCPG_POOL_MAX_SIZE	5	连接池的最大连接数。必须 ≥ MCPG_POOL_MIN_SIZE。
MCPG_STATEMENT_TIMEOUT_MS	30000	每个会话的 statement_timeout，在检出连接时设置。失控的查询会自行终止。
MCPG_LOCK_TIMEOUT_MS	5000	每个会话的 lock_timeout。卡住的锁等待会自行终止。
MCPG_ENABLE_ANALYTICAL_QUERIES	true	启用 run_analytical_query（在隔离的连接池中运行长时间读取操作）。设为 false 可撤回该工具。
MCPG_ANALYTICAL_TIMEOUT_MS	120000	run_analytical_query 每次调用的默认时间预算（2 分钟）。
MCPG_ANALYTICAL_MAX_TIMEOUT_MS	600000	run_analytical_query 的硬性上限；每次调用的 timeout_ms 会被限制在此值以内（10 分钟）。必须 ≥ MCPG_ANALYTICAL_TIMEOUT_MS。
MCPG_ANALYTICAL_MAX_CONCURRENCY	2	隔离的分析连接池大小，即同时运行的 run_analytical_query 调用数上限。
MCPG_ALLOW_INSECURE_TLS	false	绕过启动时的 TLS 检查；该检查会拒绝未设置 sslmode=require（或更强模式）的远程 DSN。本机回环主机始终豁免。
MCPG_SHUTDOWN_DRAIN_SECONDS	30	收到 SIGTERM 时，最多等待这么长时间，让正在执行的工具调用完成，然后关闭连接池和游标。

子进程工具（仅当 MCPG_ALLOW_SHELL=true 时）

变量	默认值	描述
MCPG_SHELL_TIMEOUT_SEC	60	pg_dump / pg_restore / psql 调用的最长墙钟时间。
MCPG_SHELL_MAX_OUTPUT_BYTES	67108864	（64 MiB）每次子进程调用捕获的标准输出上限。
MCPG_SUBPROCESS_BIN_ALLOWLIST	—	以逗号分隔的绝对目录列表；解析后的 pg_dump / pg_restore / psql 必须位于其中。留空 = 信任 PATH。可防止通过 PATH 垫片替换这些二进制文件。
MCPG_SUBPROCESS_CPU_SECONDS	—	每个子进程的 RLIMIT_CPU（秒）。仅限 POSIX；未设置 = 继承。
MCPG_SUBPROCESS_MEMORY_MB	—	每个子进程的 RLIMIT_AS（MiB）。仅限 POSIX；未设置 = 继承。

LISTEN/NOTIFY（仅当 MCPG_ALLOW_LISTEN=true 时）

变量	默认值	描述
MCPG_LISTEN_QUEUE_MAX	1000	每个通道的缓冲区大小；溢出时丢弃最早的通知。

审计

变量	默认值	描述
MCPG_AUDIT_PERSIST	false	为 true 时，每次 run_write / run_ddl 调用都会持久化到 mcpg_audit.events 表（自动幂等创建）。
MCPG_AUDIT_REDACT_KEYS	—	以逗号分隔的正则表达式片段，会添加到机密名称模式中（默认已涵盖 password、passwd、secret、token、api[_-]?key、bearer、authorization、database_url、dsn、conninfo）。
MCPG_AUDIT_INTEGRITY	false	为 true 时，每个持久化事件都会使用基于前一事件构建的 HMAC 链进行签名；verify_audit_chain 工具会遍历此链并报告第一个断点。需要设置 MCPG_AUDIT_HMAC_KEY。
MCPG_AUDIT_HMAC_KEY	—	用于审计 HMAC 链的密钥。MCPG_AUDIT_INTEGRITY=true 时必需。绝不会出现在 repr/日志中。

机密后端

默认情况下，所有机密都直接从环境变量中读取。设置 MCPG_SECRETS_BACKEND=file，即可改为从挂载的文件中加载 API 密钥 / bearer token / HMAC 密钥——文件中的同名值优先；文件中缺失的值会回退到环境变量，因此支持只包含部分值的文件。

变量	默认值	描述
MCPG_SECRETS_BACKEND	env	env（从环境变量读取所有机密）| file（在环境变量的基础上叠加机密文件）。
MCPG_SECRETS_FILE_PATH	—	MCPG_SECRETS_BACKEND=file 时必需。扁平的 name → value 映射文件路径：始终支持 JSON；安装了 PyYAML 时也支持 YAML（.yaml/.yml）。涵盖 ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / MCPG_NL2SQL_API_KEY、MCPG_HTTP_AUTH_TOKEN 和 MCPG_AUDIT_HMAC_KEY。

速率限制

变量	默认值	说明
MCPG_RATE_LIMIT_ENABLED	true	按工具进行令牌桶速率限制。设置为 false 可恢复重大变更前不受限制的行为。
MCPG_RATE_LIMIT_MAX_REQUESTS	60	所有工具在每个时间窗口内的全局请求上限。
MCPG_RATE_LIMIT_WINDOW_SECONDS	60	全局配额的时间窗口长度。
MCPG_RATE_LIMIT_HEAVY_MAX	5	重型工具（run_write、run_ddl、dump_database 等）的请求上限。
MCPG_RATE_LIMIT_HEAVY_WINDOW	60	重型工具配额的时间窗口长度。

缓存与功能标志

变量	默认值	说明
MCPG_CACHE_ENABLED	true	启用或禁用自适应缓存层。
MCPG_CACHE_TTL_SECONDS	300	默认缓存生存时间（秒）。
MCPG_CACHE_MAXSIZE	1024	内存缓存的 LRU 容量上限。
MCPG_REDIS_URL	—	可选的 Redis 后端连接字符串，用于外部多节点缓存。
MCPG_ENABLE_HEAVY_DIAGNOSTICS	true	切换是否启用计算量较大的诊断、图表和顾问工具。
MCPG_ELICIT_CONFIRM_WRITES	false	为 true 时，每次写入/DDL/ shell/监听/迁移层级工具调用（即任何 readOnlyHint 注解不为 true 的工具）都必须先通过交互式确认（ctx.elicit()），确认通过后才能运行。尽力而为，不构成强制执行边界：只有同时传入请求 context，并在 initialize 期间声明 elicitation 能力的客户端才会触发此机制；省略任一项的客户端都会静默绕过此门槛，工具将照常运行。

自然语言 SQL

MCPg 会在启动时自动从环境中发现每个已配置的提供商——设置任意多个厂商密钥，每个提供商都可供调用。**内置了 19 个提供商。**其中 3 个为官方提供商（Anthropic、OpenAI、Gemini）；其余 16 个通过预设厂商端点使用 OpenAI 兼容 API：DeepSeek、Qwen、OpenRouter、Perplexity、xAI （Grok）、Groq、Mistral、Together、Fireworks、DeepInfra、Cerebras、Nebius、 Hugging Face、GitHub Models、SambaNova 和 Moonshot（Kimi）。所有内置提供商均可即插即用——设置厂商惯用的 API 密钥环境变量，即可自动发现——其他任何 OpenAI 兼容厂商或本地模型服务（Ollama、vLLM、LM Studio）也都可以仅通过配置接入，使用 MCPG_NL2SQL_CUSTOM_PROVIDERS 即可。 所有内置提供商都在 nl2sql.py 中通过一个声明式注册表管理，因此添加厂商或更新已停用的默认模型只需修改一行数据。

如果未设置 MCPG_NL2SQL_PROVIDER，MCPg 会按注册表顺序自动选择默认提供商——anthropic → openai → gemini 保持优先，以免影响现有部署。translate_nl_to_sql 接受可选的 provider="…" 参数，可按调用指定提供商；get_server_info 会报告已配置的提供商。

变量	默认值	说明
<VENDOR>_API_KEY	—	设置厂商惯用密钥即可启用相应提供商。标准名称：ANTHROPIC_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY、PERPLEXITY_API_KEY、XAI_API_KEY、GROQ_API_KEY、MISTRAL_API_KEY、TOGETHER_API_KEY、FIREWORKS_API_KEY、CEREBRAS_API_KEY、NEBIUS_API_KEY、SAMBANOVA_API_KEY、MOONSHOT_API_KEY。
（密钥名称不同的厂商）	—	部分厂商不使用 <VENDOR>_API_KEY：Gemini → GEMINI_API_KEY 或 GOOGLE_API_KEY；Qwen → DASHSCOPE_API_KEY 或 QWEN_API_KEY；Hugging Face → HF_TOKEN；GitHub Models → GITHUB_TOKEN；DeepInfra → DEEPINFRA_TOKEN。
MCPG_NL2SQL_PROVIDER	自动选择	任意内置名称（见上文）或自定义名称。指定工具在调用时未提供 provider= 的情况下使用的默认提供商。未设置且存在任意厂商密钥时，MCPg 会按注册表顺序自动选择。
MCPG_NL2SQL_API_KEY	—	为已配置的 MCPG_NL2SQL_PROVIDER 指定密钥。仅覆盖该提供商的厂商惯用环境变量。必须设置 MCPG_NL2SQL_PROVIDER。
MCPG_NL2SQL_MODEL	提供商默认值	覆盖默认模型（例如 claude-sonnet-4-6、gpt-4o-mini、grok-3-mini）。仅适用于默认提供商。
MCPG_NL2SQL_BASE_URL	—	覆盖默认提供商的端点（私有网关／区域端点）。
MCPG_NL2SQL_CUSTOM_PROVIDERS	—	**接入自有提供商，无需修改代码。**使用逗号或换行分隔的 name=base_url|model 条目，声明内置提供商之外的 额外 OpenAI 兼容提供商（本地 Ollama／vLLM／LM Studio 或任何小众厂商）。密钥默认从 <NAME>_API_KEY 获取；名称不遵循此规则时，可追加 |KEY_ENV_VAR；本地回环端点允许不提供密钥。每个名称都可通过 provider= 调用。
MCPG_NL2SQL_MAX_TOKENS	2048	生成令牌数上限（硬限制：16384）。

---

使用示例

Agent（Claude、Cursor、Continue 等）会根据你的自然语言指令调用 MCP 工具。以下是一些示例对话：

查看架构

你： public 架构中有哪些表？按行数计算，哪些表最大？

Agent（使用 list_tables + summarize_table × N）： 共 6 张表：customers（120 万行）、orders（470 万行）、line_items （1,830 万行）、products（340 行）、addresses（140 万行）、audit_log （4,580 万行——最大，数据不断累积且没有保留策略）。

诊断慢查询

你： 为什么这条查询要花 8 秒？ SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days'

Agent（使用 why_is_this_slow + recommend_indexes）： EXPLAIN ANALYZE 显示，系统对 orders（470 万行）进行了顺序扫描， 并按 created_at 进行筛选。orders.created_at 上没有索引。 建议： CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); 预计提升：减少约 95% 的扫描量（索引扫描触及约 3.3 万行， 而非整张表）。应用前先对其运行 validate_migration， 确认不会遇到意外锁定。

将普通英语转换为 SQL

你： 找出本月下过订单、但此前三个月都没有下过订单的客户 ——显示他们的电子邮件和当前累计消费金额。

Agent（使用 translate_nl_to_sql）：

SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend
FROM customers c
JOIN orders o ON o.customer_id = c.id
JOIN line_items l ON l.order_id = o.id
WHERE EXISTS (
  SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id
    AND o2.created_at >= date_trunc('month', now()))
  AND NOT EXISTS (
  SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id
    AND o3.created_at >= date_trunc('month', now()) - interval '3 months'
    AND o3.created_at <  date_trunc('month', now()))
GROUP BY c.email;

查看架构图

你： 为我绘制 public 架构的 ER 图。

Agent（使用 generate_schema_diagram）： 返回 Mermaid 图表，可直接粘贴到 GitHub / Notion / Obsidian 中。

审计数据库

你： 这个数据库目前的健康状况如何？

Agent（使用 audit_database）： 返回分级报告： 内存与 I/O 得分 92（良好），事务与连接得分 78（警告： 回滚率为 0.4%，请查看应用日志），并发与锁得分 60 （严重：有 14 个后端正在等待），整洁度与膨胀得分 88（良好），慢查询 得分 70（警告：排名靠前的查询模板运行了 5000 次，平均耗时 90 毫秒 ——请参阅 optimize_query）。

执行受保护的写入操作

你： 对所有超过 5 年的订单进行软删除。

Agent（使用 run_write，并设置 MCPG_AUDIT_PERSIST=true）： 通过安全 SQL 内核验证 语句，在事务中运行该语句，返回受影响的行数，并将调用（SQL + 参数 ——已通过正则表达式对密钥进行脱敏——+ 状态）持久化到 mcpg_audit.events， 以供事后审查。

更多实用示例——多租户路由、RLS 测试、NL→SQL、 混合向量 + FTS 搜索、Apache AGE Cypher、TimescaleDB、ORM 架构 导出、服务端游标——请参阅 docs/cookbook.md。

---

包含内容

简要分类列表。完整且最新的工具参考请参阅 docs/tools.md；引导式演示请参阅 docs/tour.md。

• 目录信息检索 — 架构、表、列、索引、 约束、视图、函数、触发器、序列、分区、 策略、角色、授权、枚举、域、复合类型、FDW、 发布、订阅、扩展、生成列。
• 查询智能分析 — run_select、run_select_parallel、 explain_query、analyze_query_plan、why_is_this_slow、 recommend_indexes、analyze_workload、check_database_health、 detect_n_plus_one、audit_database。
• 搜索 — fuzzy_search（三元组）、full_text_search、 vector_search、hybrid_search（通过 RRF 使用 pgvector + FTS）、 geo_search（PostGIS k-NN）。
• 自然语言 → SQL — translate_nl_to_sql（内置 22 种 提供方——Anthropic、OpenAI、Gemini、xAI、Groq、Mistral、Hugging Face 等——还支持任何自定义的 OpenAI 兼容端点；输出会经过与手写查询相同的安全 SQL 内核）。
• 可视化 — generate_schema_diagram（ER 图）、 generate_fk_cascade_graph（ON DELETE CASCADE 的影响范围）、 generate_graph_diagram（Apache AGE 属性图）。
• 结构差异与迁移 — compare_schemas、 validate_migration，以及分阶段的 prepare_migration / complete_migration / cancel_migration 工作流。
• Apache AGE 图与 Cypher — list_graphs、describe_graph、 run_cypher、create_graph、drop_graph、generate_graph_diagram。
• 复合工具与顾问工具 — summarize_table、 find_unused_objects、find_sensitive_columns（PII 启发式检测）、 lint_naming_conventions、test_rls_for_role、list_locks、 find_blocking_chains、read_pg_stat_io（PG16+）、 generate_test_data。
• 实时运维与维护 — list_active_queries、 verify_connection_encryption（实时连接的 TLS 状态）、 run_maintenance（VACUUM/ANALYZE）、prune_audit_events （审计记录保留）、cancel_query、terminate_backend、 run_write、run_ddl、enable_extension。
• 数据迁移 — export_query / export_table（CSV/JSON）、 dump_database / restore_database、import_csv / import_json （COPY FROM STDIN）、copy_table_between_databases。
• 服务端游标 — open_cursor、fetch_cursor、 close_cursor、list_cursors，支持对数百万行数据进行分页读取。
• TimescaleDB — 超表 / 块 / 作业 / 连续聚合的 信息检索与统计信息、策略和维度管理，以及受限的 块 / 作业管理（drop_chunks、compress_chunk、 refresh_continuous_aggregate、run_job 等）。请参阅 docs/timescaledb.md。
• ORM 架构导出器 — Prisma、Drizzle、SQLAlchemy、sqlc、 Diesel、jOOQ、Ent、Ecto。
• 事件流 — subscribe_channel、poll_notifications、 unsubscribe_channel、list_notification_subscriptions，将 PostgreSQL LISTEN/NOTIFY 接入 MCP 轮询模型。
• 可观测性 — Prometheus /metrics 端点 + 面向 stdio 的 get_metrics_exposition 工具；结构化审计跟踪， 并基于正则表达式对凭据进行脱敏。

---

文档

• docs/installation.md — 安装和配置
• docs/tour.md — 工具导览
• docs/cookbook.md — 实用 Agent 配方
• docs/tools.md — 完整的工具参考
• docs/architecture.md — 各部分如何协同工作
• docs/scaling.md — 连接池大小、副本和性能
• docs/security-hardening.md — 安全路线图
• docs/release-process.md — 如何将版本发布到 PyPI
• docs/adr/ — 架构决策记录
• 浏览文档：https://devopam.github.io/MCPg/

---

安全

• 漏洞报告：请参阅 SECURITY.md。协调披露窗口为 90 天； 请将报告发送至 [email protected]。
• 深度防御：能力门控、SafeSQL 内核、标识符允许列表、审计脱敏、启动时强制执行 PG TLS、速率限制、OIDC JWT 验证、按会话设置超时。
• 请参阅 docs/security-hardening.md，了解已发布（✅）和待处理（⬜）加固项目的持续更新路线图。

隐私政策

MCPg 可自托管：数据库内容绝不会离开你的基础设施，也不会以任何形式收集遥测数据或向外发送信息。 唯一明确记载的例外是可选择启用的 translate_nl_to_sql 工具，它会将你的问题和架构上下文（名称，不含行数据）发送给你配置的大模型提供商。完整政策涵盖数据收集、使用、存储、第三方共享、保留期限和联系方式，详见 PRIVACY.md。

---

发布说明和变更日志

完整版本历史请参阅 CHANGELOG.md，有关如何制作版本发布，请参阅 docs/release-process.md，可下载的构件请访问 GitHub Releases 页面。

---

贡献

欢迎提交拉取请求 — 有关开发循环设置、测试规范和每个 PR 的审查清单，请参阅 CONTRIBUTING.md。参与行为受 行为准则 （Contributor Covenant 2.1）约束。

---

许可证

MIT — 请参阅 LICENSE。SQL 安全内核 （src/mcpg/sql/）由项目团队原创重写，源自采用 MIT 许可证的 crystaldba/postgres-mcp；来源信息请参阅 NOTICE。

封装的扩展——你应了解的许可证

MCPg 的源代码采用 MIT 许可证，但它封装的 PostgreSQL 扩展各自遵循自己的许可证。封装层与这些扩展保持独立（通过 SQL 层调用，不会静态或动态链接到 MCPg 的 Python 进程中），因此 MCPg 项目本身不构成任何扩展的衍生作品。基于 MCPg 和特定扩展构建服务的运营者，须承担该扩展许可证规定的义务——这与直接安装该扩展相同。下表列出了各个封装扩展采用的许可证，供你知情选择。

扩展	许可证	运营者须知
pgvector	PostgreSQL License（BSD 风格）	宽松；无特殊义务。
pg_partman	PostgreSQL License	宽松。
pg_cron	PostgreSQL License	宽松。
pg_turboquant	MIT	宽松。
pg_buffercache / pg_walinspect / pgstattuple	PostgreSQL contrib	宽松。
TimescaleDB	Apache 2.0（社区版）+ 部分功能采用 Timescale License（TSL，可查看源代码）	混合许可——请参阅 Timescale 的文档，了解哪些功能受 TSL 限制。
Apache AGE	Apache 2.0	宽松。
pg_search (ParadeDB)	AGPL-3.0	运营者运行的网络服务若允许用户与 pg_search 交互，则受 AGPL 网络条款约束——通常须向这些用户提供 pg_search（及任何修改）的源代码。MCPg 的封装层不会将这一义务扩展到 MCPg 本身；当你部署该扩展并通过网络“传递”它时，就要承担这项义务。如果你的服务再分发模式与 AGPL 网络条款不兼容，请选择其他 BM25 实现（BM25 计划列出了替代方案）。

此表仅供初步参考——如需针对你的具体部署获得具有约束力的答案，请查阅该扩展上游的 LICENSE 文件；如有法律相关疑问，请咨询你自己的法律顾问。

免责声明。 我们已尽最大努力使 MCPg 达到生产级质量，但它仍是一个积极开发中的项目，可能存在问题。有关赔偿责任的详情，请参阅许可条款。