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)

1. Clone or download the repository:

   cd C:/Users/Admin/Downloads/MCP/mcp_mongo
   

2. Create a virtual environment (recommended):

   uv venv
   

3. Activate the virtual environment:

   # Windows
   .venv\Scripts\activate
   
   # Linux/Mac
   source .venv/bin/activate
   

4. Install 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:

1. Module approach (recommended):

   {
     "command": "python",
     "args": ["-m", "mcp_mongo.server", "mongodb://username:password@localhost:27017/mydb"]
   }
   

2. Console script approach:

   {
     "command": "mcp-mongo",
     "args": ["mongodb://username:password@localhost:27017/mydb"]
   }
   

Available Tools

Document Operations

• list_collections() - List all collections in the database
• create_document(collection_name, document) - Insert a new document
• read_documents(collection_name, query, limit) - Find documents
• read_document_by_id(collection_name, document_id) - Find document by ID
• update_document(collection_name, query, update) - Update documents
• update_document_by_id(collection_name, document_id, update) - Update by ID
• delete_documents(collection_name, query) - Delete documents
• delete_document_by_id(collection_name, document_id) - Delete by ID
• count_documents(collection_name, query) - Count documents

Database Analysis

• get_collection_schema(collection_name) - Analyze document schema
• get_collection_indexes(collection_name) - View collection indexes
• get_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 database
• replicaSet=name - Replica set name
• ssl=true - Enable SSL/TLS
• retryWrites=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:

1. Add the function to mongodb_mcp_server.py
2. Decorate it with @mcp.tool()
3. Add proper documentation and error handling
4. 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

1. Connection refused: Ensure MongoDB is running
2. Authentication failed: Check username/password and authSource
3. Module not found: Ensure package is installed with pip install -e .
4. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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