Postgres童子军MCP
使用AI侦察您的PostgreSQL数据库-一个具有内置安全功能、监控和数据质量工具的生产就绪模型上下文协议服务器。
所得
你问：
*“我的生产数据库有多健康？有什么紧急问题吗？”*
Postgres Scout返回：
______________________________________________________________________
整体健康评分：78/100
组件分解
| 组件 | 得分 | 状态 |
|---|---|---|
| 缓存性能 | 94/100 | 正常 |
| 指标效率 | 82/100 | 良好 |
| 桌子罩衫 | 61/100 | 需要注意 |
| 连接使用率 | 75/100 | 一般 |
发现的问题
- 高 --表格
orders有34%的膨胀（浪费了2.1GB）。建议使用“真空满”。 - 中等 --3个未使用的索引
sessions消耗890MB。 - 低 --缓存命中率
analytics_events71%（目标：>90%）。
建议
- 跑
VACUUM FULL orders在维护窗口期间 - 删除未使用的索引：
idx_sessions_legacy,idx_sessions_old_token,idx_sessions_temp - 考虑添加
analytics_events共享缓冲区或按日期分区
______________________________________________________________________
那是 getHealthScore --涵盖探索、诊断、优化、监控、数据质量和安全写入的38个工具之一。
快速开始
克劳德代码
claude mcp add postgres-scout -- npx -y postgres-scout-mcp postgresql://localhost:5432/mydb然后问： *“给我看看最大的桌子，看看它们是否有膨胀的问题。”*
Claude Desktop
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"postgres-scout": {
"command": "npx",
"args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"],
"type": "stdio"
}
}
}Cursor / VS Code
添加到MCP设置中：
{
"postgres-scout": {
"command": "npx",
"args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"]
}
}Read-Only vs Read-Write
服务器运行在 默认情况下为只读模式。对于写入操作，请运行一个单独的实例：
{
"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"
}
}
}- postgres侦察机只读：安全勘探，无数据修改风险
- postgres侦察员读写：在明确需要时写入操作
工具
探索——了解您的数据库
listDatabases--用户有权访问的数据库getDatabaseStats--大小、缓存命中率、连接信息listSchemas--当前数据库中的所有模式listTables--具有大小和行统计信息的表describeTable--列、约束、索引等
查询--运行和分析
executeQuery--运行SELECT查询（或以读写模式写入）explainQuery--解释性能分析计划optimizeQuery--针对特定查询的优化建议
诊断——在他们找到你之前发现问题
getHealthScore--整体健康评分，包括成分细分detectAnomalies--性能、连接和数据异常analyzeTableBloat--真空规划的膨胀分析getSlowQueries--查询分析速度慢（需要pg_stat语句）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或SQLgenerateInsertStatements--INSERT迁移语句
写入（仅读写）-安全修改
previewUpdate/previewDelete--在承诺之前，先看看会有什么变化safeUpdate--更新干运行、行限制、空WHERE保护safeDelete--使用干运行、行限制、空WHERE保护进行删除safeInsert--插入支持验证、批处理和ON冲突
安全
- 默认情况下为只读 --必须显式启用写入操作
- 所有查询都使用参数化值
- 通过输入验证和模式检测防止SQL注入
- 表/列名的标识符清理
- 所有操作的速率限制
- 查询超时以防止长时间运行的查询
- 响应大小限制以防止内存耗尽
例子
*“最大的桌子是什么？它们有膨胀吗？”*
listTables({ schema: "public" })
analyzeTableBloat({ schema: "public", minSizeMb: 100 })*“在用户表中查找重复的电子邮件。”*
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" })配置
| 变量 | 默认值 | 描述 |
|---|---|---|
QUERY_TIMEOUT | 30000 | 查询超时（毫秒） |
MAX_RESULT_ROWS | 10000 | 每个查询返回的最大行数 |
ENABLE_RATE_LIMIT | true | 启用速率限制 |
RATE_LIMIT_MAX_REQUESTS | 100 | 每个窗口的请求 |
RATE_LIMIT_WINDOW_MS | 60000 | 速率限制窗口（ms） |
PGMAXPOOLSIZE | 10 | 连接池最大大小 |
PGMINPOOLSIZE | 2 | 连接池最小大小 |
PGIDLETIMEOUT | 10000 | 空闲连接超时（ms） |
ENABLE_LOGGING | false | 启用文件日志记录 |
LOG_DIR | ./logs | 日志文件目录 |
LOG_LEVEL | info | 日志详细程度：调试、信息、警告、错误 |
CLI标志： --read-only （默认）， --read-write, --mode
日志记录
默认情况下禁用文件日志记录。集 ENABLE_LOGGING=true 以启用。在中创建了两个日志文件 LOG_DIR:
- tool-usage.log --每个带有时间戳、名称和参数的工具调用
- 错误日志 --堆栈跟踪错误
所有输出中的连接字符串都会自动编辑。
发展
git clone https://github.com/bluwork/postgres-scout-mcp.git
cd postgres-scout-mcp
pnpm install
pnpm build
pnpm test许可证
阿帕奇-2.0