mcp-mongo-server
by: kiliczsh
A Model Context Protocol Server for MongoDB
📌Overview
Purpose: The MCP MongoDB Server allows access to MongoDB databases, enabling large language models (LLMs) to inspect collection schemas and perform various MongoDB operations.
Overview: This server provides a structured interface for interacting with MongoDB, supporting both read-only and full access modes. It facilitates efficient MongoDB operations while ensuring safety and performance.
Key Features:
-
Read-Only Mode: Connect in read-only mode to prevent write operations, enhancing safety for production databases and utilizing MongoDB's secondary read preference for better read performance.
-
Comprehensive Toolset: Includes tools for executing MongoDB queries, aggregations, updates, inserts, and more, each with detailed input requirements and outputs, allowing users to manage data effectively.
-
Collection Resources: Automatically provides schema information for each collection, including field names and data types in a JSON format, assisting users in understanding data structures quickly.
MCP MongoDB Server
A Model Context Protocol server that enables LLMs to interact with MongoDB databases. This server provides capabilities for inspecting collection schemas and executing MongoDB operations through a standardized interface.
Key Features
Smart ObjectId Handling
- Intelligent conversion between string IDs and MongoDB ObjectId
- Configurable with
objectIdMode
parameter:"auto"
: Convert based on field names (default)"none"
: No conversion"force"
: Force all string ID fields to ObjectId
Flexible Configuration
- Environment Variables:
MCP_MONGODB_URI
: MongoDB connection URIMCP_MONGODB_READONLY
: Enable read-only mode when set to "true"
- Command-line Options:
--read-only
or-r
: Connect in read-only mode
Read-Only Mode
- Protection against write operations (update, insert, createIndex)
- Uses MongoDB's secondary read preference for optimal performance
- Ideal for safely connecting to production databases
MongoDB Operations
- Read Operations:
- Query documents with optional execution plan analysis
- Execute aggregation pipelines
- Count documents matching criteria
- Get collection schema information
- Write Operations (when not in read-only mode):
- Update documents
- Insert new documents
- Create indexes
LLM Integration
- Collection completions for enhanced LLM interaction
- Schema inference for improved context understanding
- Collection analysis for data insights
Installation
Global Installation
npm install -g mcp-mongo-server
For Development
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server
npm install
npm run build
npm run watch
Usage
Basic Usage
# Start server with MongoDB URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database
# Connect in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only
Environment Variables
You can configure the server using environment variables, which is useful for CI/CD pipelines, Docker containers, or when you don't want to expose connection details in command arguments:
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"
export MCP_MONGODB_READONLY="true"
npx -y mcp-mongo-server
Example JSON for Claude Desktop configuration:
{
"mcpServers": {
"mongodb-env": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
"MCP_MONGODB_READONLY": "true"
}
}
}
}
Example Docker usage:
docker run -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" \
-e MCP_MONGODB_READONLY="true" \
mcp-mongo-server
Integration with Claude Desktop
Add the server configuration to Claude Desktop's config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Command-line Arguments Approach:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database",
"--read-only"
]
}
}
}
Environment Variables Approach:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
}
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
"MCP_MONGODB_READONLY": "true"
}
}
}
}
GitHub Package Usage:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"github:kiliczsh/mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"github:kiliczsh/mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database",
"--read-only"
]
}
}
}
Integration with Windsurf and Cursor
The MCP MongoDB Server can be used with Windsurf and Cursor in a similar way to Claude Desktop.
Windsurf Configuration
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
}
}
}
Cursor Configuration
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
}
}
}
You can also use the environment variables approach with both Windsurf and Cursor.
Automated Installation
Using Smithery:
npx -y @smithery/cli install mcp-mongo-server --client claude
Using mcp-get:
npx @michaellatman/mcp-get@latest install mcp-mongo-server
Available Tools
Query Operations
-
query: Execute MongoDB queries
{ collection: "users", filter: { age: { $gt: 30 } }, projection: { name: 1, email: 1 }, limit: 20, explain: "executionStats" // Optional }
-
aggregate: Run aggregation pipelines
{ collection: "orders", pipeline: [ { $match: { status: "completed" } }, { $group: { _id: "$customerId", total: { $sum: "$amount" } } } ], explain: "queryPlanner" // Optional }
-
count: Count matching documents
{ collection: "products", query: { category: "electronics" } }
Write Operations
-
update: Modify documents
{ collection: "posts", filter: { _id: "60d21b4667d0d8992e610c85" }, update: { $set: { title: "Updated Title" } }, upsert: false, multi: false }
-
insert: Add new documents
{ collection: "comments", documents: [ { author: "user123", text: "Great post!" }, { author: "user456", text: "Thanks for sharing" } ] }
-
createIndex: Create collection indexes
{ collection: "users", indexes: [ { key: { email: 1 }, unique: true, name: "email_unique_idx" } ] }
System Operations
- serverInfo: Get MongoDB server details
{ includeDebugInfo: true // Optional }
Debugging
Since MCP servers communicate over stdio, debugging can be challenging. Use the MCP Inspector for better visibility:
npm run inspector
This will provide a URL to access debugging tools in your browser.
License
This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License. See the LICENSE file in the project repository for details.