A
securityA
licenseA
qualityA Model Context Protocol server that provides read-only access to MongoDB databases, enabling AI assistants to directly query and analyze MongoDB data while maintaining data safety.
Last updated -
14
61
7
MIT License
Provides MongoDB database operations through CRUD functions, collection management, index management, and schema analysis tools, enabling AI assistants to interact with MongoDB databases.
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_mongoCreate a virtual environment (recommended):
uv venvActivate the virtual environment:
# Windows .venv\Scripts\activate # Linux/Mac source .venv/bin/activateInstall the package in development mode:
uv pip install -e .
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"] }
Available Tools
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")
Connection String Format
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
Adding New Tools
To add new MCP tools:
Add the function to
mongodb_mcp_server.pyDecorate 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
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Provides a standardized interface for AI assistants to interact with MongoDB databases, enabling CRUD operations, schema analysis, and database management through the Model Context Protocol.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI models to interact with both MySQL and MongoDB databases through a standardized interface, supporting comprehensive database operations including queries, schema management, and CRUD operations.Last updated -146MIT License
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to securely interact with Apache IoTDB databases through a controlled interface for listing tables, reading data, and executing SQL queries.
MongoDB MCP Serverofficial
AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with MongoDB Atlas resources through natural language, supporting database operations and Atlas management functions.Last updated -217,636664Apache 2.0