mcp-mongodb
MCP tool server providing MongoDB database access for AI agents.
Tools
| Tool | Description |
|---|---|
mongo_find |
Execute find queries with filter, projection, sort (read-only by default) |
mongo_aggregate |
Execute aggregation pipelines (read-only by default) |
mongo_list_collections |
List all collections in the database |
mongo_describe_collection |
Describe collection structure by sampling documents |
Quick Start```bash
cp .env.example .env
Edit .env with your MongoDB connection details
make install
make server
## Environment Variables
| Variable | Default | Description |
| ------------------ | ----------- | ---------------------------------------------------------- |
| `MONGODB_URI` | | Full connection string (overrides host/port/user/password) |
| `MONGODB_HOST` | `localhost` | MongoDB host |
| `MONGODB_PORT` | `27017` | MongoDB port |
| `MONGODB_USER` | | Database user |
| `MONGODB_PASSWORD` | | Database password |
| `MONGODB_DB` | `admin` | Database name |
| `MONGODB_AUTH_DB` | `admin` | Authentication database |
| `MONGODB_TLS` | `false` | Enable TLS |
| `MONGODB_READONLY` | `true` | Enforce read-only query validation |
> Set `MONGODB_READONLY=false` to enable read/write mode.
`MCP_PORT` · `8080` · Server port
## Read-Only Safety
When `MONGODB_READONLY=true` (default), two layers of protection are active:
1. **Application-level validation** — filter documents and aggregation pipelines are recursively inspected to block:
- Write stages: `$out`, `$merge`
- JavaScript execution: `$where`, `$accumulator`, `$function`
2. **Connection-level enforcement** — the MongoDB client connects with `readPreference=secondaryPreferred`, routing reads away from the primary node.
For additional security, provision the MongoDB user with only the built-in `read` role.
## Endpoints
| Path | Method | Description |
| ---------- | ------ | --------------------------------------- |
| `/healthz` | GET | Health check for K8s probes |
| `/` | GET | Server info (name, version, transports) |
| `/mcp` | POST | MCP Streamable-HTTP transport |
| `/sse` | GET | MCP SSE transport (legacy) |
## Docker```bash
make docker-build
make docker-run
