kiliczsh/mcp-mongo-server

---
A Model Context Protocol (MCP) server that lets AI assistants work with your MongoDB databases. It exposes your collections, infers their schemas, and runs queries, aggregations, and writes through a standard interface — so tools like Claude Desktop and Cursor can read and reason about your data.
Demo
Why use it
- **Talk to your database in plain language** — the assistant discovers your collections and their shape automatically.
- **Safe by default** — turn on read-only mode to let an assistant explore without any risk of changing data.
- **Works everywhere** — connects to standalone, replica set, sharded, and Atlas deployments, over plain or TLS connections.
Key Features
- **Read-Only Mode** — blocks every write path (insert, update, index creation, and aggregation stages like $out/$merge that could modify data).
- **Smart ObjectId Handling** — configurable auto/none/force conversion of 24-character hex strings to ObjectIds.
- **Schema Inference** — automatic collection schema detection from document samples.
- **Query & Aggregation** — full query and aggregation pipeline support, with optional explain plans.
- **Write Operations** — insert, update, and index creation (when read-only mode is off).
- **Time Conversion** — a convertTime helper turns Unix timestamps and date strings into UTC/GMT/ISO, so date queries stay unambiguous across timezones.
- **Progress & Cancellation** — long operations report progress and can be cancelled mid-flight.
- **Two Transports** — run locally over stdio, or expose an HTTP endpoint for remote access.
Requirements
- Node.js 20 or newer
Quick Start
Point the server at your database — no install step needed:
Explore safely, without any chance of changing data:
Usage
Local (stdio)
This is the default, used by Claude Desktop, Cursor, and other local clients:
Remote (HTTP)
Expose an HTTP endpoint at /mcp for remote or multi-client access:
By default, only requests without a browser Origin (CLIs, IDEs) and requests
from localhost are accepted; everything else is rejected with 403 to guard
against DNS-rebinding attacks. Allow specific browser origins with
--allowed-origins:
Options
| Flag | Description |
|------|-------------|
| --read-only, -r | Block all write operations |
| --allow-cross-db | Allow aggregation $out/$merge/$lookup to target other databases (off by default) |
| --allow-server-js | Allow server-side JavaScript operators $function/$where/$accumulator (off by default) |
| --transport, -t | stdio (default) or http |
| --port, -p | HTTP port (default 3001) |
| --allowed-origins | Comma-separated browser origins to allow in HTTP mode |
| --json-limit | Max HTTP request body size (default 10mb) |
| --auth-token | Require Authorization: Bearer on the HTTP endpoint |
Environment Variables
| Variable | Description |
|----------|-------------|
| MCP_MONGODB_URI | MongoDB connection URI (alternative to the argument) |
| MCP_MONGODB_READONLY | Enable read-only mode ("true") |
| MCP_MONGODB_ALLOW_CROSS_DB | Allow cross-database aggregation stages ("true") |