Unleash the Power of MongoDB with LLMs: Introducing the Model Context Protocol (MCP) Server

---

The mcp-mongo-server is a robust and versatile Model Context Protocol (MCP) server designed to seamlessly bridge the gap between Large Language Models (LLMs) and MongoDB databases. Empower your LLM applications with real-time data access, intelligent schema understanding, and the ability to execute complex MongoDB operations, all through a standardized and secure interface.

Elevate Your LLM Applications with MongoDB Integration

This server unlocks a new realm of possibilities for LLMs, enabling them to:

• Answer complex questions based on up-to-date data stored in MongoDB.
• Generate dynamic content driven by real-time database information.
• Automate tasks by executing MongoDB operations based on user input.
• Gain deeper insights through schema analysis and data exploration.

Core Capabilities: A Deep Dive

1. Intelligent ObjectId Handling: Bridging the Gap

MongoDB's ObjectId is a unique identifier, but LLMs typically work with strings. This server intelligently handles the conversion between string IDs and MongoDB ObjectIds, ensuring seamless data interaction.

• objectIdMode Parameter: Fine-tune the conversion behavior with three modes:
  • "auto" (Default): Automatically converts based on field names, providing a sensible default for most use cases.
  • "none": Disables conversion, allowing you to work directly with string representations.
  • "force": Forces all string ID fields to be treated as ObjectIds, useful for enforcing consistency.

2. Flexible Configuration: Tailor to Your Environment

Adapt the server to your specific needs with a range of configuration options:

• Environment Variables: Ideal for production deployments and CI/CD pipelines.
  • MCP_MONGODB_URI: Specifies the MongoDB connection string.
  • MCP_MONGODB_READONLY: Enables read-only mode for enhanced security.
• Command-Line Options: Convenient for quick testing and development.
  • --read-only or -r: Starts the server in read-only mode.

3. Read-Only Mode: Safeguarding Your Data

Protect your production databases with the built-in read-only mode. This feature prevents accidental or malicious write operations, ensuring data integrity.

• Enhanced Security: Disables write operations (update, insert, createIndex).
• Optimized Performance: Leverages MongoDB's secondary read preference for efficient data retrieval.

4. Comprehensive MongoDB Operations: Unleash the Full Potential

The server supports a wide range of MongoDB operations, empowering LLMs to interact with data in meaningful ways.

• Read Operations:
  • Query Documents: Retrieve data based on complex filters and projections, with optional execution plan analysis for performance optimization.
  • Execute Aggregation Pipelines: Perform advanced data transformations and analysis using MongoDB's powerful aggregation framework.
  • Count Documents: Determine the number of documents matching specific criteria.
  • Get Collection Schema Information: Understand the structure of your data for improved context and intelligent query construction.
• Write Operations (when not in read-only mode):
  • Update Documents: Modify existing data based on specific criteria.
  • Insert New Documents: Add new data to your collections.
  • Create Indexes: Optimize query performance by creating indexes on frequently accessed fields.

5. Seamless LLM Integration: A Powerful Partnership

The server is designed to work seamlessly with LLMs, providing features that enhance their understanding and capabilities.

• Collection Completions: Suggest relevant collection names to the LLM, improving user experience and reducing errors.
• Schema Inference: Provide the LLM with information about the structure of your data, enabling it to generate more accurate and relevant responses.
• Collection Analysis: Offer insights into the data stored in your collections, helping the LLM to understand the context and identify patterns.

Getting Started: Installation and Usage

Installation

Global Installation (Recommended):

npm install -g mcp-mongo-server

Development Setup:

# Clone the repository
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes and automatically rebuild
npm run watch

Basic Usage

Starting the Server:

# Start the server with your MongoDB connection URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database

# Start the server in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only

Configuration with Environment Variables

Environment variables provide a secure and flexible way to configure the server, especially in production environments.

# Set the MongoDB connection URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"

# Enable read-only mode
export MCP_MONGODB_READONLY="true"

# Run the server (it will use environment variables if no URI is provided)
npx -y mcp-mongo-server

Example: Claude Desktop Configuration with Environment Variables

{
  "mcpServers": {
    "mongodb-env": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Example: Docker Configuration with Environment Variables

docker run -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" \
           -e MCP_MONGODB_READONLY="true" \
           mcp-mongo-server

Integrating with Your Favorite Tools

The mcp-mongo-server seamlessly integrates with popular LLM development platforms like Claude Desktop, Windsurf, and Cursor.

Claude Desktop Integration

Manual Configuration:

Edit the Claude Desktop configuration file:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Example: Command-Line Arguments Approach

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Example: Environment Variables Approach

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
      }
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Example: GitHub Package Usage

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Windsurf and Cursor Integration

The integration process for Windsurf and Cursor is similar to Claude Desktop. Simply add the server configuration to your respective settings files, using either command-line arguments or environment variables.

Example: Windsurf Configuration

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Example: Cursor Configuration

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Automated Installation

Simplify the installation process with these convenient tools:

• Smithery:

  npx -y @smithery/cli install mcp-mongo-server --client claude

• mcp-get:

  npx @michaellatman/mcp-get@latest install mcp-mongo-server

Available Tools: A Comprehensive Toolkit

The server provides a rich set of tools for interacting with your MongoDB data.

Query Operations

• query: Execute MongoDB queries with flexible filtering, projection, and limiting.

  {
    collection: "users",
    filter: { age: { $gt: 30 } },
    projection: { name: 1, email: 1 },
    limit: 20,
    explain: "executionStats"  // Optional: Analyze query performance
  }

• aggregate: Run complex aggregation pipelines for advanced data analysis.

  {
    collection: "orders",
    pipeline: [
      { $match: { status: "completed" } },
      { $group: { _id: "$customerId", total: { $sum: "$amount" } } }
    ],
    explain: "queryPlanner"  // Optional: Analyze query planner
  }

• count: Count the number of documents matching specific criteria.

  {
    collection: "products",
    query: { category: "electronics" }
  }

Write Operations (Requires Non-Read-Only Mode)

• update: Modify existing documents based on a filter.

  {
    collection: "posts",
    filter: { _id: "60d21b4667d0d8992e610c85" },
    update: { $set: { title: "Updated Title" } },
    upsert: false,
    multi: false
  }

• insert: Add new documents to a collection.

  {
    collection: "comments",
    documents: [
      { author: "user123", text: "Great post!" },
      { author: "user456", text: "Thanks for sharing" }
    ]
  }

• createIndex: Create indexes to optimize query performance.

  {
    collection: "users",
    indexes: [
      {
        key: { email: 1 },
        unique: true,
        name: "email_unique_idx"
      }
    ]
  }

System Operations

• serverInfo: Retrieve detailed information about the MongoDB server.

  {
    includeDebugInfo: true  // Optional: Include debugging information
  }

Debugging: Gain Visibility into Server Operations

Debugging MCP servers that communicate over stdio can be challenging. The MCP Inspector provides valuable debugging tools:

npm run inspector

This command will provide a URL to access the debugging tools in your browser, allowing you to inspect server behavior and troubleshoot issues effectively.

License: Open Source and Ready to Use

This MCP server is licensed under the MIT License, providing you with the freedom to use, modify, and distribute the software according to your needs. See the LICENSE file in the project repository for complete details.