READMEmaster

Mongo MCP Server

An MCP (Model Context Protocol) server for interacting with MongoDB. Provides tools for querying, inserting, updating, deleting, and aggregating documents via STDIO transport.

Features

Query documents with customizable filters and limits
Insert single documents into collections
Update documents matching a filter
Delete documents matching a filter
Aggregate with full pipeline support
List all collections in the database
Count documents with optional filters
STDIO Transport compatible with MCP clients

Prerequisites

Node.js v18+
MongoDB instance (local or remote)

Installation

Clone the repository:

git clone https://github.com/stevederico/mongo-mcp.git
cd mongo-mcp

Install dependencies:
```
npm install
```
Configure environment variables — create a .env file in the root directory:
```
MONGO_URL=mongodb://localhost:27017
DB_NAME=myDatabase
```

Configuration

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "mongo-mcp": {
      "command": "node",
      "args": ["/path/to/mongo-mcp/index.js"],
      "env": {
        "MONGO_URL": "mongodb://localhost:27017",
        "DB_NAME": "myDatabase"
      }
    }
  }
}

Tools

mongo_query

Run a find query against a collection.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`query`	string	yes	JSON-stringified MongoDB query
`limit`	number	no	Max results (default: 10)

mongo_insert

Insert a single document into a collection.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`document`	string \| object	yes	Document to insert (JSON string or object)

mongo_update

Update documents matching a filter.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`filter`	string	yes	JSON-stringified filter
`update`	string	yes	JSON-stringified update operation

mongo_delete

Delete documents matching a filter.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`filter`	string	yes	JSON-stringified filter

mongo_aggregate

Run an aggregation pipeline on a collection.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`pipeline`	string	yes	JSON-stringified array of pipeline stages

mongo_list_collections

List all collection names in the connected database. No arguments.

mongo_count

Count documents in a collection with an optional filter.

Arg	Type	Required	Description
`collection`	string	yes	Target collection name
`filter`	string	no	JSON-stringified filter (default: all documents)

Dependencies

@modelcontextprotocol/sdk — MCP server framework
mongodb — MongoDB driver for Node.js
zod — Schema validation for tool arguments

License

MIT License. See LICENSE for details.

Contributing

Pull requests welcome! Open an issue to discuss changes first.