mongo-mcp

Mongo-MCP

English | 简体中文

A Machine Chat Protocol (MCP) service for MongoDB operations. This service provides a comprehensive set of tools that allow Large Language Models (LLMs) to interact with MongoDB databases through complete CRUD operations, administrative tasks, and advanced features.

Requirements

• Python 3.10 or above
• A running MongoDB database service
• It is recommended to use uv to run the program

🚀 Features

📊 Database Management Tools

• list_databases - List all databases
• create_database - Create new database
• drop_database - Delete database
• get_database_stats - Get database statistics

📦 Collection Management Tools

• list_collections - List all collections in a database
• create_collection - Create new collection (with optional settings)
• drop_collection - Delete collection
• rename_collection - Rename collection
• get_collection_stats - Get collection statistics

📄 Document CRUD Operations

• insert_document - Insert single document
• insert_many_documents - Batch insert multiple documents
• find_documents - Query documents (supports sorting, projection, limit)
• find_one_document - Query single document
• count_documents - Count documents matching query
• update_document - Update documents (single or batch)
• replace_document - Replace document
• delete_document - Delete documents (single or batch)

🔍 Index Management Tools

• list_indexes - List all indexes for a collection
• create_index - Create regular index
• create_text_index - Create text search index
• create_compound_index - Create compound index
• drop_index - Delete index
• reindex_collection - Rebuild all indexes for a collection

📈 Aggregation Operations

• aggregate_documents - Execute aggregation pipeline operations
• distinct_values - Get distinct values for a field

🔧 Monitoring and Administrative Tools

• get_server_status - Get MongoDB server status
• get_replica_set_status - Get replica set status
• ping_database - Test database connection
• test_mongodb_connection - Comprehensive connection test
• get_connection_details - Get detailed connection information

🛠️ Technology Stack

• Python: Primary programming language
• FastMCP: MCP Python SDK for automatic tool definition generation
• PyMongo: Official MongoDB Python driver
• uv: Modern Python package management tool

Usage

Run directly with uvx

uvx run mongo-mcp

The server uses the stdio transport method, making it suitable for integration with MCP clients that support this transport method.

Cursor Example Configuration

If you use Cursor as your development environment, you can add the following configuration to your .cursor/mcp.json file for local debugging:

{
    "mcpServers": {
        "mongo-mcp": {
            "command": "uvx",
            "args": [
                "mongo-mcp"
            ],
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017",
                "MONGODB_DEFAULT_DB": "your_database_name",
                "LOG_LEVEL": "INFO"
            }
        }
    }
}

Environment Variables

Basic Configuration

• MONGODB_URI: MongoDB connection string (default: "mongodb://localhost:27017")
• MONGODB_DEFAULT_DB: Default database name (optional)

Connection Pool Configuration

• MONGODB_MIN_POOL_SIZE: Minimum connection pool size (default: 0)
• MONGODB_MAX_POOL_SIZE: Maximum connection pool size (default: 100)
• MONGODB_MAX_IDLE_TIME_MS: Maximum idle time in milliseconds (default: 30000)

Timeout Configuration

• MONGODB_SERVER_SELECTION_TIMEOUT_MS: Server selection timeout (default: 30000)
• MONGODB_SOCKET_TIMEOUT_MS: Socket timeout (default: 0 - no timeout)
• MONGODB_CONNECT_TIMEOUT_MS: Connection timeout (default: 20000)

Security Configuration

• MONGODB_TLS_ENABLED: Enable TLS connection (default: false)
• MONGODB_AUTH_SOURCE: Authentication source (default: admin)
• MONGODB_AUTH_MECHANISM: Authentication mechanism (SCRAM-SHA-1, SCRAM-SHA-256, etc.)

Performance Settings

• MONGODB_READ_PREFERENCE: Read preference (default: primary)
• MONGODB_WRITE_CONCERN_W: Write concern (default: 1)
• MONGODB_READ_CONCERN_LEVEL: Read concern level (default: local)

Logging Configuration

• LOG_LEVEL: Logging level (default: "INFO")
  • Available values: DEBUG, INFO, WARNING, ERROR, CRITICAL
• LOG_MAX_FILE_SIZE: Maximum log file size in bytes (default: 10MB)
• LOG_BACKUP_COUNT: Number of backup log files (default: 5)

Feature Flags

• ENABLE_DANGEROUS_OPERATIONS: Enable potentially dangerous operations (default: false)
• ENABLE_ADMIN_OPERATIONS: Enable administrative operations (default: true)
• ENABLE_INDEX_OPERATIONS: Enable index operations (default: true)

Development Guide

1. Clone the repository

git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp

2. Install development dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"

3. Run tests

uv run pytest tests/ -v

4. Code Structure

• src/mongo_mcp/server.py: MCP server implementation
• src/mongo_mcp/db.py: Core MongoDB operations implementation
• src/mongo_mcp/config.py: Configuration management
• src/mongo_mcp/tools/: MCP tools implementation
  • database_tools.py: Database and collection management
  • document_tools.py: Document CRUD operations
  • index_tools.py: Index management
  • aggregation_tools.py: Aggregation operations
  • admin_tools.py: Administrative and monitoring tools
• src/mongo_mcp/utils/: Utility modules
• tests/: Test cases

Testing

The project includes comprehensive test coverage:

• Unit tests for all tool modules
• Integration tests with MongoDB
• Mock tests for isolated component testing

Run the test suite:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

Logging

Log files are stored in the logs directory by default. The logging system supports:

• Configurable log levels
• File rotation based on size
• UTF-8 encoding support
• Structured logging with function names and line numbers

License

MIT

Contributing

Contributions via Issues and Pull Requests are welcome. Before submitting a PR, please ensure:

1. All tests pass (uv run pytest)
2. Appropriate test cases are added
3. Documentation is updated
4. Code follows the existing style patterns