MongoDB MCP Server
A Model Context Protocol (MCP) server that provides MongoDB database operations through a standardized interface. This server enables AI assistants to interact with MongoDB databases using CRUD operations, schema analysis, and database management tools.
Features
- CRUD Operations: Create, Read, Update, Delete documents
- Collection Management: List collections, get statistics, analyze schemas
- Index Management: View and analyze database indexes
- Schema Analysis: Automatic document schema detection
- JSON Serialization: Proper handling of MongoDB ObjectIds and datetime objects
- Error Handling: Comprehensive error messages and validation
Installation
Prerequisites
- Python 3.8 or higher
- MongoDB server running
- pip (Python package installer)
Install as a Package (main)
- Clone or download the repository:
cd C:/Users/Admin/Downloads/MCP/mcp_mongo
- Create a virtual environment (recommended):
- Activate the virtual environment:
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
- Install the package in development mode:
Usage Options
1. As a Python Module
Run the server directly as a Python module:
python -m mcp_mongo.server <mongodb_connection_string>
Examples:
# Local MongoDB
python -m mcp_mongo.server "mongodb://localhost:27017/mydb"
# MongoDB with authentication
python -m mcp_mongo.server "mongodb://admin:password@localhost:27017/mydb?authSource=admin"
# MongoDB Atlas
python -m mcp_mongo.server "mongodb+srv://username:password@cluster.mongodb.net/database"
2. As a Console Script
After installation, use the console script:
mcp-mongo <mongodb_connection_string>
Examples:
# Local MongoDB
mcp-mongo "mongodb://localhost:27017/mydb"
# With authentication
mcp-mongo "mongodb://username:password@localhost:27017/db_name?authSource=admin"
3. Direct Script Execution
Run the original script directly:
python mongodb_mcp_server.py <mongodb_connection_string>
MCP Configuration
For Cursor IDE
Add this to your ~/.cursor/mcp.json:
{
"mcpServers": {
"mongodb-simple": {
"command": "<Path to python.exe in .venv>",
"args": ["-m", "mcp_mongo.server", "mongodb://username:password@localhost:27017/mydb?authSource=admin"]
}
}
}
For Other MCP Clients
Configure your MCP client to use one of these approaches:
- Module approach (recommended):
{
"command": "python",
"args": ["-m", "mcp_mongo.server", "mongodb://username:password@localhost:27017/mydb"]
}
- Console script approach:
{
"command": "mcp-mongo",
"args": ["mongodb://username:password@localhost:27017/mydb"]
}
Document Operations
list_collections() - List all collections in the databasecreate_document(collection_name, document) - Insert a new documentread_documents(collection_name, query, limit) - Find documentsread_document_by_id(collection_name, document_id) - Find document by IDupdate_document(collection_name, query, update) - Update documentsupdate_document_by_id(collection_name, document_id, update) - Update by IDdelete_documents(collection_name, query) - Delete documentsdelete_document_by_id(collection_name, document_id) - Delete by IDcount_documents(collection_name, query) - Count documents
Database Analysis
get_collection_schema(collection_name) - Analyze document schemaget_collection_indexes(collection_name) - View collection indexesget_collection_stats(collection_name) - Get collection statistics
Examples
Basic CRUD Operations
# Create a document
create_document("users", '{"name": "John Doe", "email": "john@example.com", "age": 30}')
# Read documents
read_documents("users", '{"age": {"$gte": 25}}', 10)
# Update a document
update_document("users", '{"name": "John Doe"}', '{"$set": {"age": 31}}')
# Delete documents
delete_documents("users", '{"age": {"$lt": 18}}')
Schema Analysis
# Get schema for a collection
get_collection_schema("users")
# Get collection statistics
get_collection_stats("users")
# Get indexes
get_collection_indexes("users")
The MongoDB connection string follows this format:
mongodb://[username:password@]host[:port]/database[?options]
Common options:
authSource=admin - Authentication databasereplicaSet=name - Replica set namessl=true - Enable SSL/TLSretryWrites=true - Enable retryable writes
Error Handling
The server provides detailed error messages for:
- Connection failures - Invalid connection strings, network issues
- Authentication errors - Wrong credentials, missing permissions
- Query validation - Invalid JSON, malformed queries
- Operation errors - Missing collections, constraint violations
Development
Project Structure
mcp_mongo/
├── setup.py # Package configuration
├── README.md # This file
├── pyproject.toml # Main server implementation
├── mcp_mongo/
│ ├── __init__.py # Package initialization
│ ├── server.py # Module entry point
| └── mongodb_mcp_server.py
└── .venv/ # Virtual environment
To add new MCP tools:
- Add the function to
mongodb_mcp_server.py - Decorate it with
@mcp.tool() - Add proper documentation and error handling
- Test the new functionality
Testing
Test the server with a local MongoDB instance:
# Start MongoDB (if not running)
mongod
# Test the server
python -m mcp_mongo.server "mongodb://username:password@localhost:27017/test"
Troubleshooting
Common Issues
- Connection refused: Ensure MongoDB is running
- Authentication failed: Check username/password and authSource
- Module not found: Ensure package is installed with
pip install -e . - Permission denied: Check file permissions and MongoDB user roles
Debug Mode
For debugging, check the server logs in stderr. The server provides detailed error messages for troubleshooting.
License
This project is open source. Please check the license file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Support
For issues and questions:
- Check the troubleshooting section
- Review the error messages
- Ensure MongoDB is properly configured
- Verify connection string format