io.github.bluwork/mongo-scout-mcp
Scout your MongoDB databases with AI - safety features, live monitoring, and data quality
Open source Open in the app JSON README (API)
About
Scout your MongoDB databases with AI - safety features, live monitoring, and data quality
Details
- Kind
- MCP servers
- Topic
- Databases
- Publisher
- bluwork
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.3
- Last push
- 2026-03-04T21:13:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:31
- Updated
- 2026-08-29 03:02:31
- Origin id
io.github.bluwork/mongo-scout-mcp
README
# 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.
[](https://www.npmjs.com/package/mongo-scout-mcp) [](LICENSE)
## What You Get
You ask:
> *"Anything unusual happening with order volume this month?"*
Mongo Scout returns:
---
### Volume Analysis: `orders`
**Statistics** (last 30 days)
| Metric | Value |
|--------|-------|
| Daily Average | 2,847 documents |
| Standard Deviation | 412 |
| Min / Max | 1,923 / 3,601 |
**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
```bash
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?"*
<details>
<summary>Claude Desktop</summary>
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"mongo-scout": {
"command": "npx",
"args": ["-y", "mongo-scout-mcp", "mongodb://localhost:27017", "mydb"],
"type": "stdio"
}
}
}
```
</details>
<details>
<summary>Cursor / VS Code</summary>
Add to your MCP settings:
```json
{
"mongo-scout": {
"command": "npx",
"args": ["-y", "mongo-scout-mcp", "mongodb://localhost:27017", "mydb"]
}
}
```
</details>
<details>
<summary>Read-Only vs Read-Write</summary>
The server runs in **read-only mode by default**. For write operations, run a separate instance:
```json
{
"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
</details>
## 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
| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_LOGGING` | `false` | Enable file logging |
| `LOG_DIR` | `./logs` | Log file directory |
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:
```json
{ "_id": { "$oid": "507f1f77bcf86cd799439011" } }
{ "_id": "507f1f77bcf86cd799439011" }
```
## Development
```bash
git clone https://github.com/bluwork/mongo-scout-mcp.git
cd mongo-scout-mcp
pnpm install
pnpm build
pnpm test
```
## License
Apache-2.0