mongo-scout-mcp

Mongo Scout MCP

借助 AI 探索 MongoDB 数据库——一款适用于生产环境的 Model Context Protocol 服务，内置安全功能、实时监控和数据质量工具。

你将获得什么

你可以询问：

“这个月的订单量有什么异常吗？”

Mongo Scout 会返回：

订单量分析：orders

统计数据（过去 30 天）

检测到的异常

• 2 月 14 日 — 5,892 个文档（+7.4σ）— 情人节峰值
• 2 月 22 日 — 847 个文档（-4.9σ）— 支付网关中断时段
• 3 月 1 日 — 4,201 个文档（+3.3σ）— 月初订阅续费

建议

• 2 月 22 日的下降值得调查——中断期间可能发生了数据丢失
• 考虑针对可预测的峰值（如月初、节假日）设置自动扩缩容规则
• 为超过滚动平均值 ±3σ 的订单量设置提醒

这由 detectVolumeAnomalies 实现——它是 50 个工具之一，涵盖数据库探索、查询、诊断、监控、数据质量和安全写入。

快速开始

Claude Code

claude mcp add mongo-scout -- npx -y mongo-scout-mcp mongodb://localhost:27017 mydb

然后询问：“我有哪些集合？它们的架构是什么样的？”

{
  "mcpServers": {
    "mongo-scout": {
      "command": "npx",
      "args": ["-y", "mongo-scout-mcp", "mongodb://localhost:27017", "mydb"],
      "type": "stdio"
    }
  }
}

{
  "mongo-scout": {
    "command": "npx",
    "args": ["-y", "mongo-scout-mcp", "mongodb://localhost:27017", "mydb"]
  }
}

{
  "mcpServers": {
    "mongo-scout-readonly": {
      "command": "npx",
      "args": ["-y", "mongo-scout-mcp", "--read-only", "mongodb://localhost:27017", "mydb"],
      "type": "stdio"
    },
    "mongo-scout-readwrite": {
      "command": "npx",
      "args": ["-y", "mongo-scout-mcp", "--read-write", "mongodb://localhost:27017", "mydb_dev"],
      "type": "stdio"
    }
  }
}

工具

探索——了解你的数据库

• listDatabases — 实例中的所有数据库
• getDatabaseStats — 存储和性能统计数据
• listCollections — 当前数据库中的集合
• getCollectionStats — 大小、文档数量和索引详情
• inferSchema — 根据抽样文档推断架构

查询——查找和分析文档

• find — 使用筛选、排序和投影查询文档
• aggregate — 运行聚合管道
• count — 统计符合查询条件的文档
• distinct — 获取字段的唯一值
• textSearch — 在已建立索引的字段中进行全文搜索
• explainQuery — 分析查询执行计划

诊断——及早发现问题

• detectVolumeAnomalies — 检测文档数量中的异常模式
• analyzeQueryPerformance — 使用 explain 计划优化查询

监控——实时监控

• getServerStatus — 服务器性能指标
• getCurrentOperations — 当前正在运行的操作
• getConnectionPoolStats — 连接池状态
• getProfilerStats — 分析器数据和慢速操作
• getLiveMetrics — 持续更新的实时指标
• getHottestCollections — 活动量最高的集合
• getCollectionMetrics — 各集合的详细指标
• getSlowestOperations — 慢查询追踪
• runAdminCommand — 执行管理命令

数据质量——确保数据可信

• findDuplicates — 按字段组合查找重复文档
• findOrphans — 跨集合查找孤立引用
• findMissingFields — 查找缺少必需字段的文档
• findInconsistentTypes — 查找文档间的类型不一致
• validateDocuments — 使用 MongoDB $expr 进行自定义验证

关系——追踪引用

• exploreRelationships — 多跳关系遍历

时间序列——时间分析

• findRecent — 查找指定时间窗口内的文档
• findInTimeRange — 按日期范围查询，可选择分组

索引 — 管理索引

• listIndexes — 集合的所有索引
• createIndex — 创建新索引
• dropIndex — 删除索引

导出 — 导出数据

• exportCollection — 导出为 JSON、JSONL 或 CSV
• cloneCollection — 克隆集合，并支持筛选和复制索引

预览 — 更改前先试运行

• previewUpdate / previewDelete — 提交前查看将发生的更改
• previewBulkWrite — 预览批量操作

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

• insertOne / insertMany — 插入文档
• updateOne / updateMany — 更新，并支持 dryRun 和 maxDocuments 限制
• replaceOne — 替换单个文档
• findOneAndUpdate — 查找并以原子方式更新
• deleteOne / deleteMany — 删除，并支持 dryRun 和 maxDocuments 限制
• bulkWrite — 在一次调用中执行多个写入操作
• renameField — 重命名字段，并支持试运行和索引迁移
• createCollection / dropCollection — 管理集合

安全性

• 默认只读 — 必须显式启用写入操作
• 所有查询都会经过验证和清理
• 防止 MongoDB 运算符注入
• 日志中的连接字符串凭据会被隐藏
• 对所有操作进行速率限制
• 限制响应大小，以防止内存耗尽

示例

“我有哪些集合？users 的架构是什么？”

listCollections()
inferSchema({ collection: "users", sampleSize: 50 })

“查找 users 集合中的重复电子邮件地址。”

findDuplicates({ collection: "users", fields: ["email"], options: { limit: 100 } })

“显示上个月订单量的异常情况。”

detectVolumeAnomalies({ collection: "orders", timestampField: "createdAt", options: { groupBy: "day", lookbackPeriods: 30 } })

“服务器现在是什么情况？”

getServerStatus()
getCurrentOperations()
getHottestCollections({ limit: 5, sampleDuration: 5000 })

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

findOrphans({ collection: "orders", localField: "userId", foreignCollection: "users", foreignField: "_id" })

“将 products 集合导出为 CSV。”

exportCollection({ collection: "products", options: { format: "csv", flatten: true } })

配置

CLI 参数：--read-only（默认）、--read-write、--mode <mode>

日志记录

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

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

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

ObjectId 格式

接受以下两种格式：

{ "_id": { "$oid": "507f1f77bcf86cd799439011" } }
{ "_id": "507f1f77bcf86cd799439011" }

开发

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

许可证

Apache-2.0