/ 目录 / 演练场 / Postgres
● 官方 modelcontextprotocol 🔑 需要你的密钥

Postgres

作者 modelcontextprotocol · modelcontextprotocol/servers

让 Claude 以只读安全的方式查询你的 Postgres 数据库,完整的 schema 内省和执行计划支持 — 无需授予任何写入权限。

Postgres 标准 MCP server。用标准 postgres:// URL 连接,提供 schema 浏览、查询执行和 EXPLAIN。严格只读 — 无 INSERT/UPDATE/DELETE/DDL — 可以安全地指向生产读副本。

为什么要用

核心特性

实时演示

实际使用效果

postgres.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://..."
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://...

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Postgres

无需接触 SQL 即可回答临时业务问题

👤 产品经理、创始人、不想写 SQL 的人 ⏱ ~10 min beginner

何时使用: 你有关于数据的问题(比如「本周有多少用户回访?」),而 BI 仪表板上找不到答案。

前置条件
  • 读副本的只读 postgres:// 连接字符串 — 大多数托管的 Postgres(RDS、Neon、Supabase)都支持创建只读凭据
  • 从 Claude 运行的地方到数据库的网络访问 — VPN 或 IP 允许列表中加入你的机器
步骤
  1. 先让 Claude 内省相关的表
    列出我们 DB 里的所有表。对于与用户、订单或会话相关的表,描述它们的 schema。✓ 已复制
    → 查询前的 schema 概览
  2. 提出实际问题
    过去 30 天内注册但还没下过单的用户有多少?按注册周分组。✓ 已复制
    → Claude 编写 SQL、执行并返回结果表
  3. 探查注意事项
    这个数字有可能有误吗?软删除?created_at 的时区?需要排除某些特定的用户类型吗?✓ 已复制
    → 诚实指出数据的特点

结果: 针对业务问题的一个站得住脚的答案,包含 SQL、结果和注意事项 — 2 分钟内完成,而不用等数据团队 2 天。

注意事项
  • Claude 写的查询不加限制地扫描你最大的表 — 在连接上设置 statement_timeout = '30s',并在 system prompt 里加上「默认总是包含 LIMIT 1000」
  • 「用户」的计数取决于如何定义用户(包括删除的?机器人?测试账户?) — 提前告诉 Claude 你的约定:「排除 deleted_at IS NOT NULL 的行」等等。
搭配使用: notion

诊断查询为什么慢,并建议索引

👤 后端工程师、DBA ⏱ ~15 min intermediate

何时使用: 你有个查询速度不如预期。你想要另一双眼睛帮你看 EXPLAIN ANALYZE 输出,而不用担心审美疲劳。

步骤
  1. 获取查询计划
    对这个查询运行 EXPLAIN ANALYZE:[粘贴]。给我讲解一下规划器在做什么。✓ 已复制
    → 逐步的计划演练
  2. 找出成本驱动因素
    哪一步占了大部分成本?是顺序扫描、join 顺序不好还是昂贵的过滤?✓ 已复制
    → 指出具体节点及原因
  3. 建议添加索引或重写查询
    建议最小的改动来加快速度。优先选择添加索引而不是重写查询,但前提是这个索引要对多个查询有用。✓ 已复制
    → 具体的 CREATE INDEX 语句或重写的查询

结果: 一个添加了索引或重写的查询,带有推理过程,你可以再次运行 EXPLAIN 验证。

注意事项
  • 在非代表性数据集(小的开发 DB)上运行 EXPLAIN 会得到误导的计划 — 总是针对有生产规模数据的数据库运行 EXPLAIN;否则计划就是虚构的
  • 添加索引似乎没有成本,但会拖累写入速度 — 让 Claude 在建议你添加索引前,先通过 EXPLAIN 验证这个索引会被使用
搭配使用: sentry

审计表的数据质量问题

👤 数据工程师、继承陌生 schema 的人 ⏱ ~25 min intermediate

何时使用: 你即将在你没有设计的表上构建功能,怀疑它可能有问题。

步骤
  1. 运行一套 NULL/重复/孤立行检查
    对于 orders 表:计算每列的 NULL 值数、按自然键计算重复行(如 (user_id, stripe_payment_intent_id))、计算外键指向已删除父行的行数。✓ 已复制
    → 每个检查的问题计数
  2. 检查值的分布是否有异常
    对于 total_cents,最小值、最大值和百分位分布是什么?有可疑的很多 0 或负值行吗?✓ 已复制
    → 分布统计,异常值被标记
  3. 交叉检查预期的业务规则
    每个「已完成」的订单应该有非空的 paid_at。有例外吗?✓ 已复制
    → 违规数量 + 样本 ID

结果: 一个简短的具体数据完整性 bug 列表,每个都有计数和修复路径。

注意事项
  • 一些「问题」是故意留下的历史遗迹(数据迁移) — 在假设这是个 bug 前,总是和了解历史的人确认一下

为团队自动生成 schema 文档

👤 让新工程师快速上手的技术负责人 ⏱ ~20 min beginner

何时使用: 你的 DB 有 40 张表,wiki 上 0 张。新员工总是问「这列是什么?」

步骤
  1. 获取所有表和它们的 schema
    列出 public schema 里的所有表。对于每一张,给我列、类型、可空性、默认值和外键。✓ 已复制
    → 完整的 schema 转储
  2. 从命名和样本数据推断目的
    对于每张表,采样 3 行,写一段话描述这张表在我们业务中代表什么。✓ 已复制
    → 每个表的文本说明
  3. 标记未知的或可疑的表
    有没有看起来未被使用或者你无法推断其目的的表?列出来,我去问原作者。✓ 已复制
    → 诚实的「我不知道这些是什么」列表

结果: 一个 Markdown 文档,你的团队可以放到 Notion 或 wiki 里 — 涵盖新员工需要了解的 80% 内容。

注意事项
  • 把敏感数据(PII)采样到 LLM context 中 — 对于包含 PII 的表,只让 Claude 描述 schema 不采样行
搭配使用: notion · filesystem

从原始事件数据计算 A/B 测试结果

👤 产品分析师、增长工程师 ⏱ ~30 min advanced

何时使用: 你运行了个实验,数据在你的 DB 里,你想要显著性数字但不想手写 SQL。

前置条件
  • 包含实验分配 + 转化事件的事件表 — 标准 schema:events(user_id, experiment, variant, timestamp)、conversions(user_id, type, timestamp)
步骤
  1. 计算每个变体的转化率
    对于「checkout-redesign-2026」实验:每个变体分配了多少用户?[你的转化事件]的转化率是多少?✓ 已复制
    → 带有转化率的每个变体表
  2. 计算统计显著性
    计算对照组和处理组差异的卡方 p 值。结果在 p < 0.05 水平上统计显著吗?✓ 已复制
    → 带有结论的 p 值
  3. 检查数字的合理性
    样本量平衡吗?实验运行时间足够长吗?有没有某些分组的结果相反?✓ 已复制
    → 健康检查,不仅仅是 p 值

结果: 一个统计上站得住脚的 A/B 测试结果,包含 SQL、数字和注意事项。

注意事项
  • 在达到预先定义的样本量前就查看结果会导致假阳性 — 让 Claude 在计算显著性前检查测试是否达到目标样本量
搭配使用: notion

组合

与其他 MCP 搭配,撬动十倍杠杆

postgres + notion

运行查询,把结果作为 Notion 表发布给没有 DB 访问权限的利益相关者

查询本季度按终身收入排名前 10 的客户,然后在「Sales Reports」里创建一个 Notion 页面,把结果作为格式化表格。✓ 已复制
postgres + sentry

将 DB 状态与错误交叉引用 — 当错误提到记录 ID 时,查一下

Sentry issue WEB-3a91 提到 order_id 99214。查一下那个订单,告诉我行数据中有没有什么能解释这个崩溃。✓ 已复制
postgres + filesystem

将查询结果导出为 CSV/JSON 供下游使用

运行我的 churn-cohort 查询,把结果保存为 /reports/churn-2026-04.csv。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_tables schema?: str 任何会话的第一步 — 发现 schema free
describe_table table: str, schema?: str 在查询前获取特定表的完整结构 free
query sql: str 运行任何只读 SQL — 仅 SELECT depends on query

成本与限制

运行它的成本

API 配额
受你的 DB 连接限制和查询超时限制
每次调用 Token 数
Schema 查询:~500 token。结果集:取决于行数 — 用 LIMIT 限制
费用
免费 — 成本就是你的 DB 托管费
提示
总是在连接上设置 statement_timeout(如 ?options=-c%20statement_timeout%3D30000),这样失控的查询就不能搞垮你的 DB。

安全

权限、密钥、影响范围

最小权限: 你想要暴露的表上的 SELECT
凭据存储: 连接字符串在环境变量中。使用专门的只读角色:CREATE ROLE claude_readonly LOGIN PASSWORD '...'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
数据出站: 所有查询都发往你的 DB;结果行被发往你使用的 LLM 提供商
切勿授予: INSERT UPDATE DELETE DROP TRUNCATE ALTER

故障排查

常见错误与修复

FATAL: password authentication failed

检查连接字符串。常见原因:密码中的特殊字符未进行 URL 编码。

验证: psql 'postgres://...' -c 'SELECT 1'
no pg_hba.conf entry / SSL required

在连接字符串后附加 ?sslmode=require。大多数托管的 Postgres 需要 SSL。

permission denied for table X

该角色对这个表没有 SELECT 权限。运行 GRANT SELECT ON X TO claude_readonly

验证: psql -c '\dp X'
canceling statement due to statement timeout

查询太慢了。要么优化它(添加索引、缩小 WHERE 子句),要么提高那个连接的超时。

替代方案

Postgres 对比其他方案

替代方案何时用它替代权衡
Supabase MCP你在用 Supabase — 获取完整的项目管理加 SQL包含写入权限;对生产来说不够安全
Neon MCP你在用 Neon — 增加了分支功能用于安全的迁移测试Neon 特定功能只能在 Neon DB 上使用
dbHub你需要在一个 MCP 中支持多个数据库(Postgres、MySQL、MongoDB 等)比较新;支持更多 DB,但每个集成都比较浅
sqlite MCP本地基于文件的 DB 而不是服务器没有并发访问、没有网络,但零配置

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills