Mongo
    Mongo

    Mongo

    A Model Context Protocol Server for MongoDB

    4.3

    GitHub Stats

    Stars

    245

    Forks

    40

    Release Date

    6/6/2025

    about a month ago

    Detailed Description

    mcp mongodb server


    npm version npm downloads npm license smithery badge verified on mseep

    a model context protocol server that enables llms to interact with mongodb databases. this server provides capabilities for inspecting collection schemas and executing mongodb operations through a standardized interface.

    demo

    mcp mongodb server demo | claude desktop

    key features

    smart objectid handling

    • intelligent conversion between string ids and mongodb objectid
    • configurable with objectidmode parameter:
      • "auto": convert based on field names (default)
      • "none": no conversion
      • "force": force all string id fields to objectid

    flexible configuration

    • environment variables:
      • mcp_mongodb_uri: mongodb connection uri
      • mcp_mongodb_readonly: enable read-only mode when set to "true"
    • command-line options:
      • --read-only or -r: connect in read-only mode

    read-only mode

    • protection against write operations (update, insert, createindex)
    • uses mongodb's secondary read preference for optimal performance
    • ideal for safely connecting to production databases

    mongodb operations

    • read operations:
      • query documents with optional execution plan analysis
      • execute aggregation pipelines
      • count documents matching criteria
      • get collection schema information
    • write operations (when not in read-only mode):
      • update documents
      • insert new documents
      • create indexes

    llm integration

    • collection completions for enhanced llm interaction
    • schema inference for improved context understanding
    • collection analysis for data insights

    installation

    global installation

    npm install -g mcp-mongo-server
    

    for development

    # clone repository
    git clone https://github.com/kiliczsh/mcp-mongo-server.git
    cd mcp-mongo-server
    
    # install dependencies
    npm install
    
    # build
    npm run build
    
    # development with auto-rebuild
    npm run watch
    

    usage

    basic usage

    # start server with mongodb uri
    npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database
    
    # connect in read-only mode
    npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only
    

    environment variables

    you can configure the server using environment variables, which is particularly useful for ci/cd pipelines, docker containers, or when you don't want to expose connection details in command arguments:

    # set mongodb connection uri
    export mcp_mongodb_uri="mongodb://muhammed:kilic@localhost:27017/database"
    
    # enable read-only mode
    export mcp_mongodb_readonly="true"
    
    # run server (will use environment variables if no uri is provided)
    npx -y mcp-mongo-server
    

    using environment variables in claude desktop configuration:

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

    using environment variables with docker:

    # build
    docker build -t mcp-mongo-server .
    
    # run
    docker run -it -d -e mcp_mongodb_uri="mongodb://muhammed:kilic@localhost:27017/database" -e mcp_mongodb_readonly="true" mcp-mongo-server
    
    # or edit docker-compose.yml and run
    docker-compose up -d
    

    integration with claude desktop

    manual configuration

    add the server configuration to claude desktop's config file:

    macos: ~/library/application support/claude/claude_desktop_config.json windows: %appdata%/claude/claude_desktop_config.json

    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"
          ]
        }
      }
    }
    

    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"
          }
        }
      }
    }
    

    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"
          ]
        }
      }
    }
    

    integration with windsurf and cursor

    the mcp mongodb server can be used with windsurf and cursor in a similar way to claude desktop.

    windsurf configuration

    add the server to your windsurf configuration:

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

    cursor configuration

    for cursor, add the server configuration to your settings:

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

    you can also use the environment variables approach with both windsurf and cursor, following the same pattern shown in the claude desktop configuration.

    automated installation

    using smithery:

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

    using mcp-get:

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

    available tools

    query operations

    • query: execute mongodb queries

      {
        collection: "users",
        filter: { age: { $gt: 30 } },
        projection: { name: 1, email: 1 },
        limit: 20,
        explain: "executionstats"  // optional
      }
      
    • aggregate: run aggregation pipelines

      {
        collection: "orders",
        pipeline: [
          { $match: { status: "completed" } },
          { $group: { _id: "$customerid", total: { $sum: "$amount" } } }
        ],
        explain: "queryplanner"  // optional
      }
      
    • count: count matching documents

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

    write operations

    • update: modify documents

      {
        collection: "posts",
        filter: { _id: "60d21b4667d0d8992e610c85" },
        update: { $set: { title: "updated title" } },
        upsert: false,
        multi: false
      }
      
    • insert: add new documents

      {
        collection: "comments",
        documents: [
          { author: "user123", text: "great post!" },
          { author: "user456", text: "thanks for sharing" }
        ]
      }
      
    • createindex: create collection indexes

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

    system operations

    • serverinfo: get mongodb server details
      {
        includedebuginfo: true  // optional
      }
      

    debugging

    since mcp servers communicate over stdio, debugging can be challenging. use the mcp inspector for better visibility:

    npm run inspector
    

    this will provide a url to access the debugging tools in your browser.

    running evals

    the evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. you can load environment variables by prefixing the npx command. full documentation can be found here.

    openai_api_key=your-key  npx mcp-eval src/evals/evals.ts src/schemas/tools.ts
    

    license

    this mcp server is licensed under the mit license. this means you are free to use, modify, and distribute the software, subject to the terms and conditions of the mit license. for more details, please see the license file in the project repository.

    Star History

    Star History

    Dec 8Feb 7Mar 7Mar 20Mar 31Apr 12Apr 23May 6May 26Jun 30060120180240
    Powered by MSeeP Analytics

    About the Project

    Owners:

    Muhammed KılıçMuhammed Kılıç

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.