postgres-scout-mcp

Postgres Scout MCP

借助 AI 探查 PostgreSQL 数据库——一款可用于生产环境的模型上下文协议服务，内置安全功能、监控和数据质量工具。

你将获得什么

你可以询问：

“我的生产数据库运行状况如何？有没有紧急问题？”

Postgres Scout 会返回：

总体健康评分：78/100

组件评分

发现的问题

• 高 — 表 orders 的膨胀率为 34%（浪费 2.1 GB）。建议执行 VACUUM FULL。
• 中 — sessions 上有 3 个未使用的索引，占用 890 MB。
• 低 — analytics_events 的缓存命中率为 71%（目标：>90%）。

建议

• 在维护时段运行 VACUUM FULL orders
• 删除未使用的索引：idx_sessions_legacy、idx_sessions_old_token、idx_sessions_temp
• 考虑将 analytics_events 加入 shared_buffers，或按日期分区

这就是 getHealthScore 的功能——它是 38 个工具之一，涵盖数据库探索、诊断、优化、监控、数据质量和安全写入。

快速开始

Claude Code

claude mcp add postgres-scout -- npx -y postgres-scout-mcp postgresql://localhost:5432/mydb

然后询问：“显示最大的表，并告诉我它们是否存在膨胀问题。”

{
  "mcpServers": {
    "postgres-scout": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"],
      "type": "stdio"
    }
  }
}

{
  "postgres-scout": {
    "command": "npx",
    "args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"]
  }
}

{
  "mcpServers": {
    "postgres-scout-readonly": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "--read-only", "postgresql://localhost:5432/production"],
      "type": "stdio"
    },
    "postgres-scout-readwrite": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "--read-write", "postgresql://localhost:5432/development"],
      "type": "stdio"
    }
  }
}

工具

探索 — 了解数据库

• listDatabases — 用户有权访问的数据库
• getDatabaseStats — 大小、缓存命中率、连接信息
• listSchemas — 当前数据库中的所有架构
• listTables — 表及其大小和行数统计
• describeTable — 列、约束、索引等信息

查询 — 执行并分析

• executeQuery — 执行 SELECT 查询（或在读写模式下执行写入操作）
• explainQuery — 使用 EXPLAIN 执行计划进行性能分析
• optimizeQuery — 针对特定查询提供优化建议

诊断 — 在问题找上门前发现它们

• getHealthScore — 总体健康评分及组件评分
• detectAnomalies — 检测性能、连接和数据异常
• analyzeTableBloat — 分析表膨胀情况，为 VACUUM 规划提供依据
• getSlowQueries — 慢查询分析（需要 pg_stat_statements）
• suggestVacuum — 根据死元组和膨胀情况提供 VACUUM 建议

优化 — 提升速度

• suggestIndexes — 根据查询模式推荐缺失的索引
• suggestPartitioning — 为大型表提供分区策略
• getIndexUsage — 找出未使用或使用率低的索引

监控 — 实时监控

• getCurrentActivity — 活动查询和连接
• analyzeLocks — 锁争用和阻塞查询
• getLiveMetrics — 指定时间窗口内的实时指标
• getHottestTables — 活动量最高的表
• getTableMetrics — 每张表全面的 I/O 和扫描统计信息

数据质量 — 确保数据可信

• findDuplicates — 按列组合查找重复行
• findMissingValues — 分析各列中的 NULL 值
• findOrphans — 查找外键无效的孤立记录
• checkConstraintViolations — 在添加约束前测试是否存在违规
• analyzeTypeConsistency — 分析文本列中的类型不一致问题

关系 — 沿连接进行探索

• exploreRelationships — 多跳外键遍历
• analyzeForeignKeys — 外键健康状况和性能

时间序列 — 时间分析

• findRecent — 时间窗口内的行
• analyzeTimeSeries — 窗口函数和异常检测
• detectSeasonality — 季节性模式检测

导出 — 导出数据

• exportTable — CSV、JSON、JSONL 或 SQL
• generateInsertStatements — 用于迁移的 INSERT 语句

写入（仅读写模式）— 安全修改

• previewUpdate / previewDelete — 提交前查看将发生的更改
• safeUpdate — 支持试运行、行数限制和空 WHERE 保护的 UPDATE
• safeDelete — 支持试运行、行数限制和空 WHERE 保护的 DELETE
• safeInsert — 支持验证、批处理和 ON CONFLICT 的 INSERT

安全

• 默认只读 — 必须显式启用写入操作
• 所有查询均使用参数化值
• 通过输入验证和模式检测防止 SQL 注入
• 对表名和列名进行标识符清理
• 对所有操作进行速率限制
• 设置查询超时，防止查询长时间运行
• 限制响应大小，防止内存耗尽

示例

“哪些表最大？它们是否存在膨胀？”

listTables({ schema: "public" })
analyzeTableBloat({ schema: "public", minSizeMb: 100 })

“查找 users 表中的重复电子邮件。”

findDuplicates({ table: "users", columns: ["email"] })

“哪些查询最慢？如何加快它们？”

getSlowQueries({ minDurationMs: 100, limit: 10 })
suggestIndexes({ schema: "public" })

“向我展示数据库当前正在发生什么。”

getCurrentActivity()
getLiveMetrics({ metrics: ["queries", "connections", "cache"], duration: 30000, interval: 1000 })
getHottestTables({ limit: 5, orderBy: "seq_scan" })

“查找引用了已删除客户的孤立订单。”

findOrphans({ table: "orders", foreignKey: "customer_id", referenceTable: "customers", referenceColumn: "id" })

配置

CLI 标志：--read-only（默认）、--read-write、--mode <mode>

日志记录

默认情况下禁用文件日志记录。设置 ENABLE_LOGGING=true 即可启用。系统会在 LOG_DIR 中创建两个日志文件：

• tool-usage.log — 每次工具调用的时间戳、名称和参数
• error.log — 包含堆栈跟踪的错误

所有输出中的连接字符串都会自动脱敏。

开发

git clone https://github.com/bluwork/postgres-scout-mcp.git
cd postgres-scout-mcp
pnpm install
pnpm build
pnpm test

许可证

Apache-2.0