MCPg

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

在线试用： 将 MCP 客户端——或 MCP Inspector——指向托管的只读演示端点 https://devopam-mcpg-demo.hf.space/mcp。它针对一次性演示数据提供只读工具；实际使用时，请在您自己的数据库旁边运行 MCPg（参见快速开始）。

📍 已收录于

• 官方 MCP 注册表

• mcp.so

• mcpservers.org

• Smithery

• Glama

为什么选择 MCPg

• 默认安全。 只读访问模式。每条用户提供的 SQL 语句在执行前都会通过经过验证的 AST 允许列表进行解析。标识符插值通过严格的 [A-Za-z_][A-Za-z0-9_]* 正则表达式流转——这一设计约束意味着用户输入永远不会通过字符串拼接到达数据库。DDL、shell 和 LISTEN/NOTIFY 等功能默认关闭，直到您选择启用。每个工具都会发布源自相同门控的 MCP ToolAnnotations（readOnlyHint、openWorldHint），因此客户端可以自动批准读取操作并在无需猜测的情况下对写入操作进行门控。

• 一个服务器，广泛覆盖。 应用数据访问（查询、搜索、游标、NL→SQL）以及 DBA 级操作（健康检查、索引调优、EXPLAIN 分析、锁、vacuum、转储、副本、迁移）都集成在单个 MCP 服务器中。代理无需切换工具即可切换任务。

• 一切皆 PostgreSQL 原生。 无 ORM，无抽象开销——直接使用 psycopg3，支持所有 pg_* 系统视图，在可用时与 TimescaleDB、pgvector、PostGIS、Apache AGE 和 pg_stat_statements 集成，在不可用时优雅降级。

• 面向生产，而非演示。 连接池、按请求 SET ROLE 多租户、带降级主机检测的只读副本路由、带专用连接的服务器端游标、速率限制、带正则表达式脱敏的审计跟踪、启动时 PG TLS 强制、OIDC JWT 承载认证、按会话的语句/锁超时。

• 内置可观测性。 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（测试版） 作为实验性（非阻塞）条目，在 issue #120 下跟踪。

Related MCP server: PostgreSQL MCP Server

安装

从 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 和 Command Prompt 代码块。

或者从源码自行构建：

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 的 Settings → Extensions）。系统会提示您输入 PostgreSQL 连接 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 提问，例如：

"这个数据库中有哪些 schema？对于每个 schema，总结最大的三张表。"

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

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

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

一条命令即可将一个小型、精选的电商数据集（3,000 个订单、900 条产品评论、故意埋入的缺陷）填充到 mcpg_demo schema 中——经过精心设计，让索引顾问、查询计划分析、全文搜索、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 传输）。设置 MCPG_HTTP_AUTH_TOKEN=... 以使用静态承载令牌，或设置 MCPG_AUTH_MODE=oidc 以针对 OIDC 颁发者进行完整的 JWT 验证。

配置

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

常见场景

完整参考

核心

能力门控（面向更高爆炸半径工具的可选启用）

认证（仅 HTTP 传输）

HTTP 加固（仅 HTTP 传输）

多租户（SET ROLE）

只读副本

多数据库（只读辅助数据库）

连接池 / 超时 / TLS

子进程工具（仅限 MCPG_ALLOW_SHELL=true）

LISTEN/NOTIFY（仅 MCPG_ALLOW_LISTEN=true 时）

审计

密钥后端

默认情况下，每条机密都直接从环境中读取。设置 MCPG_SECRETS_BACKEND=file 可改为从挂载的文件加载 API 密钥 / bearer token / HMAC 密钥 —— 文件中的名称优先；文件中缺失的项会回退到环境变量，因此只写部分字段的文件也能工作。

速率限制

缓存与功能开关

自然语言 SQL

MCPg 在启动时会自动从环境中发现每个已配置的提供商，你配置多少个提供商的密钥，就会有多少个可调用。内置了十九个提供商。 其中三家为第一方（Anthropic、OpenAI、Gemini），其余十六个使用 OpenAI 兼容 API，并由厂商预设好端点：DeepSeek、Qwen、OpenRouter、Perplexity、xAI（Grok）、Groq、Mistral、Together、Fireworks、DeepInfra、Cerebras、Nebius、Hugging Face、GitHub Models、SambaNova 和 Moonshot（Kimi）。每个内置提供商都是即插即用的——设置该供应商通行的 API-key 环境变量后即可自动发现——并且任何其他 OpenAI 兼容提供商或本地模型服务器（Ollama、vLLM、LM Studio）仍可仅通过配置接入，通过 MCPG_NL2SQL_CUSTOM_PROVIDERS。整个内置列表只是一个声明式注册表，位于 nl2sql.py 中，因此新增一个提供商或刷新一个已退役的默认模型，只需普普通通的一行数据改动。

当 MCPG_NL2SQL_PROVIDER 未设置时，MCP 的默认选择按注册表顺序自动选取——anthropic → openai → gemini 排在前面，因此现有部署不受影响。translate_nl_to_sql 可接受可选的 provider="…" 参数来按单次调用路由；get_server_info 会报告哪些提供商已配置。

使用示例

MCP 工具由智能体（Claude、Cursor、Continue……）根据你的自然语言指令调用。下面是一些有代表性的往返示例：

检查模式

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

智能体（使用 list_tables + summarize_table × N）： 共六张表：customers（1.2M 行）、orders（4.7M）、line_items （18.3M）、products（340）、addresses（1.4M）、audit_log （45.8M——最大，且没有保留策略，持续累积）。

诊断慢查询

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

智能体（使用 why_is_this_slow + recommend_indexes）： EXPLAIN ANALYZE 显示，对 orders（4.7M 行）按 created_at 过滤时进行了顺序扫描。 orders.created_at 上没有索引。建议： CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); 预期改进：约减少 95%（索引扫描只需触及约 33K 行，而非整张表）。 应用前先对其运行 validate_migration，确认不会有锁相关的意外。

将自然语言转换为 SQL

你： 找出本月下过单但前三个月从未下过单的客户——显示他们的邮箱和当前累计消费金额。

智能体（使用 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 图。

智能体（使用 generate_schema_diagram）： 返回一张可以直接粘贴到 GitHub / Notion / Obsidian 的 Mermaid 图。

审计数据库

你： 这个数据库现在的运行状况如何？

智能体（使用 audit_database）： 返回一份分级报告： 内存与 I/O 评分 92（GOOD）、事务与连接 78（WARNING：回滚率 0.4%，请检查应用日志）、并发与锁 60 （CRITICAL：14 个后台进程在等待）、整洁度与膨胀 88（GOOD）、慢查询 70（WARNING：最高频的 查询模板执行 5000 次，平均 90 ms——参见 optimize_query）。

执行受保护的写入

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

智能体（使用 run_write 并设置 MCPG_AUDIT_PERSIST=true）： 通过 safe-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（trigram）、full_text_search、vector_search、hybrid_search（pgvector + FTS，通过 RRF）、geo_search（PostGIS k-NN）。

• 自然语言 → SQL — translate_nl_to_sql（内置 22 家提供商——Anthropic、OpenAI、Gemini、xAI、Groq、Mistral、Hugging Face……——以及任何自定义的兼容 OpenAI 的端点；输出与手写查询一样，会经过同一个 safe-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 — list_hypertables、list_chunks、create_hypertable、add_compression_policy、add_retention_policy。

• 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 — 实用智能体配方

• 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 天协调披露窗口；报告发送至 devopam@gmail.com。

• 纵深防御：能力门控、SafeSQL 内核、标识符白名单、审计脱敏、启动时强制 PG TLS、速率限制、OIDC JWT 校验、每会话超时。

• 参见 docs/security-hardening.md 了解已发布（✅）和已排队（⬜）加固项的动态路线图。

隐私政策

MCPg 是自托管的：你的数据库内容永远不会离开你的基础设施，并且没有任何形式的遥测或回传。唯一有记录的例外是可选加入的 translate_nl_to_sql 工具，它会将你的问题以及模式上下文（名称，而非行数据）发送给由你配置的 LLM 提供商。完整政策——数据收集、使用、存储、第三方共享、保留期限和联系方式——见 PRIVACY.md。

发布说明与变更日志

完整版本历史参见 CHANGELOG.md，发布流程参见 docs/release-process.md，可下载的构建产物参见 GitHub Releases 页面。

贡献

欢迎提交 Pull Request——有关开发循环设置、测试约定和每个 PR 的审查清单，请参见 CONTRIBUTING.md。

许可证

MIT——参见 LICENSE。SQL 安全内核（src/mcpg/sql/）是第一方代码，根据 MIT 许可的 crystaldba/postgres-mcp 重新编写；来源参见 NOTICE。

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

MCPg 的源代码采用 MIT 许可证，但它封装的 PostgreSQL 扩展各自带有自己的许可证。这些封装本身保持一定距离（SQL 级调用，不静态或动态链接到 MCPg 的 Python 进程），因此 MCPg 项目本身不是其中任何一个的衍生作品。部署基于 MCPg + 特定扩展构建的服务的运维人员，需要承担该扩展许可证所施加的任何义务——与直接安装该扩展相同。下表列出了每个封装扩展的许可证，以便你做出明智的选择。

此矩阵只是一个起点——要获得针对你具体部署的具有约束力的答案，请查阅扩展的上游 LICENSE 文件，以及（如果法律上重要的话）咨询你自己的法律顾问。

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