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?"

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

Add to your MCP settings:

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

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