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):
uv venv
Activate the virtual environment:
# Windows .venv\Scripts\activate # Linux/Mac source .venv/bin/activate
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:

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 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:

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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

MongoDB MCP Server
jonfreeland
A
security
A
license
A
quality
A 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
25
7
MIT License
MCP-MongoDB-MySQL-Server
yaoxiaolinglong
A
security
A
license
A
quality
A 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 -
14
6
MIT License
IoTDB MCP Server
JackieTien97
-
security
F
license
-
quality
A 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.
Last updated -
MongoDB MCP Serverofficial
mongodb-js
A
security
A
license
A
quality
A 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 -
21
9,553
581
Apache 2.0

View all related MCP servers

MongoDB MCP Server