io.github.bluwork/mongo-scout-mcp

Mongo Scout MCP

Scout your MongoDB databases with AI - A production-ready Model Context Protocol server with built-in safety features, live monitoring, and data quality tools.

What You Get

You ask:

"Anything unusual happening with order volume this month?"

Mongo Scout returns:

Volume Analysis: orders

Statistics (last 30 days)

Anomalies Detected

• Feb 14 — 5,892 documents (+7.4σ) — Valentine's Day spike
• Feb 22 — 847 documents (-4.9σ) — Payment gateway outage window
• Mar 1 — 4,201 documents (+3.3σ) — Month-start subscription renewals

Recommendations

• Feb 22 drop warrants investigation — possible data loss during outage
• Consider auto-scaling rules for predictable spikes (month boundaries, holidays)
• Set up alerts for volumes exceeding ±3σ from rolling average

That's detectVolumeAnomalies — one of 50 tools covering exploration, querying, diagnostics, monitoring, data quality, and safe writes.

Quick Start

Claude Code

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

Then ask: "What collections do I have and what do their schemas look like?"

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Cursor / VS Code

Add to your MCP settings:

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

Read-Only vs Read-Write

The server runs in read-only mode by default. For write operations, run a separate instance:

{
  "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"
    }
  }
}

• mongo-scout-readonly: Safe exploration, no risk of data modification
• mongo-scout-readwrite: Write operations when explicitly needed

Tools

Explore — understand your database

• listDatabases — all databases in the instance
• getDatabaseStats — storage and performance statistics
• listCollections — collections in the current database
• getCollectionStats — size, document count, index details
• inferSchema — schema inference from sampled documents

Query — find and analyze documents

• find — query documents with filtering, sorting, projection
• aggregate — run aggregation pipelines
• count — count documents matching a query
• distinct — unique values for a field
• textSearch — full-text search across indexed fields
• explainQuery — query execution plan analysis

Diagnose — spot problems early

• detectVolumeAnomalies — unusual patterns in document volume
• analyzeQueryPerformance — query optimization using explain plans

Monitor — watch it live

• getServerStatus — server performance metrics
• getCurrentOperations — currently running operations
• getConnectionPoolStats — connection pool health
• getProfilerStats — profiler data and slow operations
• getLiveMetrics — real-time metrics with continuous updates
• getHottestCollections — collections with highest activity
• getCollectionMetrics — detailed per-collection metrics
• getSlowestOperations — slow query tracking
• runAdminCommand — execute admin commands

Data Quality — trust your data

• findDuplicates — duplicate documents by field combination
• findOrphans — orphaned references across collections
• findMissingFields — documents missing required fields
• findInconsistentTypes — type inconsistencies across documents
• validateDocuments — custom validation with MongoDB $expr

Relationships — follow the references

• exploreRelationships — multi-hop relationship traversal

Time Series — temporal analysis

• findRecent — documents within a time window
• findInTimeRange — date range queries with optional grouping

Indexes — manage your indexes

• listIndexes — all indexes for a collection
• createIndex — create new indexes
• dropIndex — remove indexes

Export — get data out

• exportCollection — JSON, JSONL, or CSV
• cloneCollection — clone with filtering and index copying

Preview — dry-run before changing anything

• previewUpdate / previewDelete — see what would change before committing
• previewBulkWrite — preview bulk operations

Write (read-write only) — safe modifications

• insertOne / insertMany — insert documents
• updateOne / updateMany — update with dryRun and maxDocuments limits
• replaceOne — replace a single document
• findOneAndUpdate — find and update atomically
• deleteOne / deleteMany — delete with dryRun and maxDocuments limits
• bulkWrite — multiple write operations in one call
• renameField — rename fields with dry-run and index migration
• createCollection / dropCollection — collection management

Security

• Read-only by default — write operations must be explicitly enabled
• All queries are validated and sanitized
• MongoDB operator injection protection
• Connection string credential redaction in logs
• Rate limiting on all operations
• Response size limits to prevent memory exhaustion

Examples

"What collections do I have and what's the schema of users?"

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

"Find duplicate emails in the users collection."

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

"Show me order volume anomalies over the last month."

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

"What's happening on the server right now?"

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

"Find orders that reference deleted users."

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

"Export the products collection as CSV."

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

Configuration

CLI flags: --read-only (default), --read-write, --mode <mode>

Logging

File logging is disabled by default. Set ENABLE_LOGGING=true to enable. Two log files are created in LOG_DIR:

• tool-usage.log — every tool call with timestamp, name, and arguments
• error.log — errors with stack traces

Connection strings are automatically redacted in all output.

ObjectId Format

Both formats accepted:

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

Development

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

License

Apache-2.0