MongoDB MCP Server

A Model Context Protocol (MCP) server that provides MongoDB database access for Claude Code. This server allows you to query MongoDB databases directly from Claude with configurable connection parameters.

Features

• Master User Management: Find users by platform ID, email, account ID, or user ID

• Invoice Management: Search and retrieve invoices by account ID or invoice ID

• Connection Health: Check MongoDB connection status and health

• Flexible Configuration: Support for command-line arguments, environment variables, and config files

• Error Handling: Graceful fallback when database is unavailable

Installation

Option 1: Using mcp add (Recommended)

cd your-project-directory
mcp add https://github.com/sergei-tofu-fedorov/mongo_mcp.git

Then edit the generated .mcp.json to add your connection parameters:

{
  "mcpServers": {
    "mongo_mcp": {
      "command": "npx",
      "args": [
        "mongo-mcp-server",
        "--uri", "mongodb://your-host:27017",
        "--db", "your-database-name"
      ]
    }
  }
}

Option 2: Install from npm (coming soon)

npm install -g mongo-mcp-server

Option 3: Install from GitHub

npm install -g git+https://github.com/sergei-tofu-fedorov/mongo_mcp.git

Option 4: Clone and install locally

git clone https://github.com/sergei-tofu-fedorov/mongo_mcp.git
cd mongo_mcp
npm install
npm link  # Make it available globally

Usage

Method 1: Configure via .mcp.json (Recommended)

Add the server to your .mcp.json file in any project directory:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp-server",
        "--mongo-uri", "mongodb://your-host:27017",
        "--database", "your-database-name"
      ]
    }
  }
}

Or with environment variables:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["mongo-mcp-server"],
      "env": {
        "MONGODB_URI": "mongodb://your-host:27017",
        "MONGODB_DATABASE": "your-database-name"
      }
    }
  }
}

Method 2: Install locally in project

1. Clone this repo into your project or install as dependency

2. Create a settings.json file in the project root:

{
  "mongodb": {
    "uri": "mongodb://your-host:27017",
    "database": "your-database-name"
  }
}

3. Add to your .mcp.json:

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["./path/to/mongo_mcp/server.js"]
    }
  }
}

Configuration Priority

The server accepts configuration in the following priority order:

1. Command-line arguments (highest priority)

   # Full format
   mongo-mcp-server --mongo-uri mongodb://localhost:27017 --database mydb
   
   # Short format
   mongo-mcp-server --uri mongodb://localhost:27017 --db mydb
   
   # Single URI format (with database in path)
   mongo-mcp-server mongodb://localhost:27017/mydb

2. Environment variables

   export MONGODB_URI="mongodb://localhost:27017"
   export MONGODB_DATABASE="mydb"
   mongo-mcp-server

3. settings.json file

   {
     "mongodb": {
       "uri": "mongodb://localhost:27017",
       "database": "mydb"
     }
   }

4. Default values (lowest priority)

   • URI: mongodb://localhost:27017

   • Database: mcpserver

Available Tools

Connection Management

• check_connection: Check if MongoDB connection is active and healthy

Master User Tools

• find-master-user-by-platform-id: Find master user by platform ID (case-insensitive search)

  • Parameters: platformId (string), limit (number, default: 10)

• find-master-user-by-email: Find master user by email (case-insensitive search)

  • Parameters: email (string), limit (number, default: 10)

• find-master-user-by-id: Find a specific master user by their ID

  • Parameters: id (string)

• find-master-user-by-account-id: Find master user by account ID (case-insensitive search)

  • Parameters: accountId (string), limit (number, default: 10)

Invoice Tools

• find-invoices-by-account-id: Find invoices by account ID (case-insensitive search)

  • Parameters: accountId (string), limit (number, default: 10)

• find-invoice-by-id: Find a specific invoice by its ID

  • Parameters: id (string)

Quick Start with mcp add

1. Navigate to any directory where you want to use MongoDB tools:

   cd C:\AI\mongo_test

2. Add the MongoDB MCP server:

   mcp add https://github.com/sergei-tofu-fedorov/mongo_mcp.git

3. Edit the generated .mcp.json file to add your MongoDB connection:

   {
     "mcpServers": {
       "mongo_mcp": {
         "command": "npx",
         "args": [
           "mongo-mcp-server",
           "mongodb://your-host:27017/your-database"
         ]
       }
     }
   }

4. Start Claude Code:

   claude-code

5. Use MongoDB tools directly in Claude:

   find master user by email john@example.com
   find invoices by account 2djcl2neh9-0f9f3bd0e
   check mongodb connection status

Example Usage in Claude Code

Once configured, you can use these tools directly in Claude Code:

find master user by email john@example.com
find invoices by account 2djcl2neh9-0f9f3bd0e
check mongodb connection status

Development

Requirements

• Node.js >= 18.0.0

• MongoDB instance (local or remote)

Running in Development

git clone https://github.com/sergei-tofu-fedorov/mongo_mcp.git
cd mongo_mcp
npm install
npm run dev  # Runs with --watch for auto-reload

Testing with Different Configurations

# Test with command line args
node server.js --mongo-uri mongodb://localhost:27017 --database testdb

# Test with environment variables
MONGODB_URI=mongodb://localhost:27017 MONGODB_DATABASE=testdb node server.js

# Test with settings.json (create the file first)
node server.js

Troubleshooting

Connection Issues

• Verify MongoDB is running and accessible

• Check firewall settings and network connectivity

• Ensure the URI format is correct: mongodb://host:port or mongodb+srv://cluster.example.com

• Validate database name and permissions

Permission Issues

• Ensure the MongoDB user has read permissions on the target database

• Check that the user can access the required collections

MCP Server Issues

• Verify Claude Code can find the server executable

• Check the .mcp.json configuration syntax

• Look for error messages in Claude Code's output

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.