前置条件
- 1已安装 Node.js 18 及以上版本（提供 npx 命令）
- 2已安装 Claude Code CLI（claude 命令可用）
- 3有一个可连接的 PostgreSQL 数据库（本地或远程均可）
- 4拥有数据库管理员权限，能创建只读账号
使用示例
1自动生成业务报表
使用示例
统计最近 30 天每天的订单量和 GMV，按日期升序输出，并标出环比下跌超过 30% 的日期预期效果
自动识别订单表的时间字段与金额字段类型 生成带 date_trunc 的分组聚合 SQL 并执行 用窗口函数计算环比，直接标出异常日期 结果以表格形式返回，并附上可能的归因分析
2慢查询与索引优化
使用示例
这条 SQL 跑了 8 秒，帮我看看执行计划，给出索引优化建议：
SELECT * FROM orders WHERE user_id = 123 AND status = 'paid' ORDER BY created_at DESC LIMIT 20;预期效果
读取目标表的现有索引定义 基于字段选择性判断应建复合索引及字段顺序 给出可直接执行的 CREATE INDEX 语句 说明索引带来的写入代价，避免盲目加索引
3数据核对与异常排查
使用示例
orders 表和 payments 表按 order_id 关联，帮我找出有订单但没有支付记录的脏数据，统计数量并列出前 10 条预期效果
自动判断两表的关联字段与外键关系 用 LEFT JOIN 或 NOT EXISTS 找出缺失记录 返回数量统计与样本数据 给出数据补全或清理的建议方案
4把表结构转成代码
使用示例
读一下 users 表的结构，帮我生成对应的 TypeScript 类型定义和一个带分页的查询函数预期效果
精确映射 Postgres 类型到 TypeScript（含可空字段） 生成完整的 interface 定义与分页查询函数 自动补上参数校验与总条数统计 代码可直接复制到项目中使用
常见问题
Q执行 claude mcp list 显示连接失败（Failed to connect）怎么办？
先用 psql 或 pg_isready 用同一串连接串手工连一次，确认账号密码与端口无误。常见原因是密码中含有 @ # : 等特殊字符未做 URL 编码，请改用百分号编码（如 @ 写成 %40），或改用环境变量传连接串。远程库还需确认 pg_hba.conf 允许你的 IP 访问。
Q提示 spawn npx ENOENT 是什么问题？
Claude Code 找不到 npx，说明 Node.js 未安装或不在系统 PATH 中。执行 node -v 与 npx -v 检查；Windows 用户若在 Git Bash 中安装，请改用官方安装包重装 Node.js 并重启终端。
QMCP 连上了，但 Claude 说看不到任何表？
多半是权限没给全。确认已执行 GRANT USAGE ON SCHEMA 与 GRANT SELECT ON ALL TABLES，且 schema 名不是 public 时要换成实际 schema。另外只读账号默认看不到其他 schema 下的表，需要显式授权。
Q可以让 Claude 直接写库、改数据吗？
官方 server-postgres 只暴露只读查询能力，任何 INSERT、UPDATE、DROP 都会被拒绝。这是刻意的安全设计，不要为了图方便去换用可执行写操作的第三方 server。确实需要写库时，让 Claude 生成 SQL 脚本，人工审核后在 psql 中执行。