MongoDB MCP Server

A Model Context Protocol server that provides tools for interacting with MongoDB databases. This server enables AI models to query, aggregate, and manage MongoDB data through standardized MCP tools.

Features

Query MongoDB collections with filtering, projection, sorting, and pagination
Count documents matching a query filter
Perform complex aggregation operations
Find distinct values in a collection
List available databases and collections
Automatic handling of MongoDB ObjectIds
Rate limiting to prevent abuse

Installation

npm install

Environment Variables

The server requires the following environment variables:

MONGODB_URI: The MongoDB connection string (required)

Example:

MONGODB_URI="mongodb://username:password@localhost:27017/mydatabase"

Usage

Starting the Server

Build and start the server:

npm run build
npm start

For development with automatic rebuilding:

npm run dev

Available Tools

The MongoDB MCP server provides the following tools:

1. `mongodb_query`

Performs a query operation on a MongoDB collection.

Parameters:

database (required): MongoDB database name
collection (required): MongoDB collection name
filter: Query filter in MongoDB format (e.g. { "field": "value" })
projection: Fields to include/exclude in MongoDB format (e.g. { "field": 1 })
sort: Sort specification in MongoDB format (e.g. { "field": 1 } for ascending)
limit: Maximum number of documents to return (1-100, default 10)
skip: Number of documents to skip (default 0)

2. `mongodb_count`

Counts the number of documents in a MongoDB collection that match a query filter.

Parameters:

database (required): MongoDB database name
collection (required): MongoDB collection name
filter: Query filter in MongoDB format (e.g. { "field": "value" })

3. `mongodb_aggregate`

Performs an aggregation operation on a MongoDB collection.

Parameters:

database (required): MongoDB database name
collection (required): MongoDB collection name
pipeline (required): Aggregation pipeline stages in MongoDB format
limit: Maximum number of documents to return (1-100, default 10)

4. `mongodb_distinct`

Finds the distinct values for a specified field across a MongoDB collection.

Parameters:

database (required): MongoDB database name
collection (required): MongoDB collection name
field (required): Field for which to return distinct values
filter: Query filter in MongoDB format (e.g. { "field": "value" })

5. `mongodb_list_databases`

Lists all available databases in the MongoDB server.

Parameters:

filter: Optional filter for the returned databases

6. `mongodb_list_collections`

Lists all collections in a specified MongoDB database.

Parameters:

database (required): MongoDB database name
filter: Optional filter for the returned collections

Examples

Querying Documents

{
  "database": "mydatabase",
  "collection": "users",
  "filter": { "age": { "$gt": 18 } },
  "projection": { "name": 1, "email": 1, "_id": 0 },
  "sort": { "name": 1 },
  "limit": 5
}

Counting Documents

{
  "database": "mydatabase",
  "collection": "orders",
  "filter": { "status": "completed" }
}

Aggregation Example

{
  "database": "mydatabase",
  "collection": "sales",
  "pipeline": [
    { "$match": { "date": { "$gte": "2023-01-01" } } },
    { "$group": { "_id": "$product", "totalSales": { "$sum": "$amount" } } },
    { "$sort": { "totalSales": -1 } }
  ],
  "limit": 10
}

Finding Distinct Values

{
  "database": "mydatabase",
  "collection": "products",
  "field": "category",
  "filter": { "active": true }
}

Docker Deployment

This server includes a Dockerfile for containerized deployment. To build and run:

docker build -t mongodb-mcp-server .
docker run -e MONGODB_URI="mongodb://username:password@host:27017/mydatabase" mongodb-mcp-server

License

MIT

MongoDB MCP Server