Claude Code 接入 PostgreSQL MCP 完整指南

Claude Code 接入 PostgreSQL MCP 完整指南

本教程将带你把 PostgreSQL MCP Server 接入 Claude Code，让 AI 能够直接读取你的数据库结构、执行只读查询、生成报表 SQL 并给出索引优化建议。

配置完成后，你不再需要手动导出 CSV、粘贴建表语句、截图结果集——直接用自然语言描述需求，Claude 会自己去看表、写 SQL、跑查询、解释结果。

为什么要用 MCP 直连数据库

在写代码或排查线上问题时，最常见的卡点是「AI 不知道你的表长什么样」。传统做法与 MCP 方案的对比：

MCP（Model Context Protocol）本质是一套标准协议，让 AI 客户端以统一方式调用外部工具。数据库是它最适合落地的场景之一。

步骤一：检查运行环境

在开始配置前，先确认四个命令都能正常输出。

1node -v          # 建议 v18 及以上
2npx -v           # Node 自带，用于拉取 MCP Server
3claude --version # 确认 Claude Code CLI 已安装
4pg_isready -h localhost -p 5432   # 确认数据库可连通，正常返回 accepting connections

步骤二：创建专用的只读数据库账号

这一步是整套方案的安全基石：永远不要用 superuser 或应用主账号连接 MCP。

用管理员账号登录数据库，创建一个只能读、不能写的专用角色：

1-- 1. 创建只读角色（请替换为强密码）
2CREATE ROLE claude_readonly LOGIN PASSWORD '换成强密码';
3
4-- 2. 允许连接目标库
5GRANT CONNECT ON DATABASE mydb TO claude_readonly;
6
7-- 3. 允许读取 public schema
8GRANT USAGE ON SCHEMA public TO claude_readonly;
9
10-- 4. 授予现有所有表的只读权限
11GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
12
13-- 5. 未来新建的表也自动可读，避免以后反复授权
14ALTER DEFAULT PRIVILEGES IN SCHEMA public
15  GRANT SELECT ON TABLES TO claude_readonly;

验证只读是否生效：

1psql "postgresql://claude_readonly:你的密码@localhost:5432/mydb" -c "\dt"

步骤三：注册 PostgreSQL MCP Server

推荐用命令行添加，无需手工编辑配置文件。

1claude mcp add postgres -s user -- \
2  npx -y @modelcontextprotocol/server-postgres \
3  "postgresql://claude_readonly:你的密码@localhost:5432/mydb"

命令拆解：

• postgres — 这个 MCP Server 在本机的名字，后面 /mcp 里显示的就是它
• -s user — 作用域，可选 local（当前项目，默认）、project（写入 .mcp.json 随仓库共享）、user（当前用户全局可用）
• -- — 分隔符，后面的内容全部当作启动命令
• 最后一段是数据库连接串

三种作用域怎么选

如果偏好手写配置，等价的 .mcp.json 写法如下：

1{
2  "mcpServers": {
3    "postgres": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "@modelcontextprotocol/server-postgres",
8        "postgresql://claude_readonly:你的密码@localhost:5432/mydb"
9      ]
10    }
11  }
12}

远程数据库需要 SSL 时，在连接串末尾追加参数：

1postgresql://claude_readonly:密码@db.example.com:5432/mydb?sslmode=require

步骤四：验证连接状态

1claude mcp list

启动 Claude Code 并进入交互界面，输入 /mcp 查看所有 MCP Server 的实时状态。

步骤五：第一次提问

现在直接用自然语言提问，Claude 会自己调用 MCP 工具去探索数据库：

接入后可以稳定使用的四类能力：

场景应用示例

场景1：自动生成业务报表

使用示例：

预期效果：

• 自动识别订单表的时间字段与金额字段类型
• 生成带 date_trunc 的分组聚合 SQL 并执行
• 用窗口函数计算环比，直接标出异常日期
• 结果以表格形式返回，并附上可能的归因分析

场景2：慢查询与索引优化

使用示例：

1这条 SQL 跑了 8 秒，帮我看看执行计划，给出索引优化建议：
2SELECT * FROM orders WHERE user_id = 123 AND status = 'paid' ORDER BY created_at DESC LIMIT 20;

预期效果：

• 读取目标表的现有索引定义
• 基于字段选择性判断应建复合索引及字段顺序
• 给出可直接执行的 CREATE INDEX 语句
• 说明索引带来的写入代价，避免盲目加索引

场景3：数据核对与异常排查

使用示例：

预期效果：

• 自动判断两表的关联字段与外键关系
• 用 LEFT JOIN 或 NOT EXISTS 找出缺失记录
• 返回数量统计与样本数据
• 给出数据补全或清理的建议方案

场景4：把表结构转成代码

使用示例：

预期效果：

• 精确映射 Postgres 类型到 TypeScript（含可空字段）
• 生成完整的 interface 定义与分页查询函数
• 自动补上参数校验与总条数统计
• 代码可直接复制到项目中使用

安全红线

数据库接入 AI 是强能力，也是高风险操作，以下五条建议务必遵守：

常见问题排查

进阶玩法

• 多数据源并行：用不同名字添加多个 server（如 postgres_orders、postgres_users），Claude 会在同一轮对话中自动选择对应数据源
• 远程 MCP 服务：企业内可自建 HTTP MCP 服务，用 claude mcp add team-db --url https://mcp.company.com/postgres 接入，统一管控凭据
• 与 Filesystem MCP 组合：一边读库一边读写代码文件，让 Claude 直接生成与表结构同步的 Repository 层代码
• 沉淀 SQL 片段库：把高频查询整理成 .sql 文件放进项目，配合 Filesystem MCP 让 AI 直接复用