MongoDB Lens MCP server

MongoDB Lens is a local Model Context Protocol (MCP) server that enables natural language interactions with MongoDB databases. It allows you to perform queries, run aggregations, optimize performance, and manage your databases using conversational language through any MCP-compatible client like Claude Desktop.

Installation

MongoDB Lens can be installed and run in several ways:

NPX (Easiest)

Make sure Node.js is installed on your system:

node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible

Then run MongoDB Lens via NPX:

# Using default connection string mongodb://localhost:27017
npx -y mongodb-lens

# Using custom connection string
npx -y mongodb-lens mongodb://your-connection-string

# Using "@latest" to keep the package up-to-date
npx -y mongodb-lens@latest

Docker Hub

Make sure Docker is installed:

docker --version # Ideally >= v27.x

Run MongoDB Lens via Docker Hub:

# Using default connection string mongodb://localhost:27017
docker run --rm -i --network=host furey/mongodb-lens

# Using custom connection string
docker run --rm -i --network=host furey/mongodb-lens mongodb://your-connection-string

# Using "--pull" to keep the Docker image up-to-date
docker run --rm -i --network=host --pull=always furey/mongodb-lens

Node.js from Source

1. Clone the repository:

   git clone https://github.com/furey/mongodb-lens.git
   

2. Navigate to the cloned directory:

   cd /path/to/mongodb-lens
   

3. Install dependencies:

   npm ci
   

4. Start the server:

   # Using default connection string mongodb://localhost:27017
   node mongodb-lens.js
   
   # Using custom connection string
   node mongodb-lens.js mongodb://your-connection-string
   

Docker from Source

1. Clone the repository:

   git clone https://github.com/furey/mongodb-lens.git
   

2. Navigate to the cloned directory:

   cd /path/to/mongodb-lens
   

3. Build the Docker image:

   docker build -t mongodb-lens .
   

4. Run the container:

   # Using default connection string mongodb://localhost:27017
   docker run --rm -i --network=host mongodb-lens
   
   # Using custom connection string
   docker run --rm -i --network=host mongodb-lens mongodb://your-connection-string
   

Verification

To verify the installation, paste this JSONRPC message into the server's stdio:

{"method":"resources/read","params":{"uri":"mongodb://databases"},"jsonrpc":"2.0","id":1}

You should receive a list of databases in your MongoDB instance.

Configuration

MongoDB Connection String

MongoDB Lens accepts a MongoDB connection string as its only argument:

npx -y mongodb-lens@latest mongodb://your-connection-string

Connection strings have the following format:

mongodb://[username:password@]host[:port][/database][?options]

Examples:

• Local connection: mongodb://localhost:27017
• With credentials: mongodb://username:password@hostname:27017/mydatabase?authSource=admin
• With options: mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority

Config File

MongoDB Lens supports extensive customization via a JSON configuration file located at:

• ~/.mongodb-lens.jsonc (preferred) or
• ~/.mongodb-lens.json

You can customize the config file path by setting the CONFIG_PATH environment variable.

To generate a configuration file:

# Generate config file
npx -y mongodb-lens@latest config:create

# Force overwrite existing file
npx -y mongodb-lens@latest config:create -- --force

Multiple MongoDB Connections

You can configure multiple MongoDB URIs with aliases:

{
  "mongoUri": {
    "main": "mongodb://localhost:27017",
    "backup": "mongodb://localhost:27018",
    "atlas": "mongodb+srv://username:[email protected]/mydb"
  }
}

The first URI becomes the default connection at startup. You can switch connections using natural language: "Connect to backup" or "Connect to atlas".

Client Setup

Claude Desktop

1. Install Claude Desktop
2. Open or create claude_desktop_config.json:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the MongoDB Lens server configuration:

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/npx",
      "args": [
        "-y",
        "mongodb-lens@latest",
        "mongodb://your-connection-string"
      ]
    }
  }
}

4. Restart Claude Desktop
5. Start a conversation with Claude about your MongoDB data

MCP Inspector

MCP Inspector is useful for testing and debugging:

# Run MCP Inspector with MongoDB Lens
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

# With custom connection string
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest mongodb://your-connection-string

Then open http://localhost:5173 to access the inspector interface.

Data Protection

Read-Only User Accounts

For better security, consider using read-only credentials:

// In MongoDB shell:
use admin
db.createUser({
  user: 'readonly',
  pwd: 'eXaMpLePaSsWoRd',
  roles: [{ role: 'read', db: 'mydatabase' }]
})

Then connect using those credentials:

mongodb://readonly:eXaMpLePaSsWoRd@localhost:27017/mydatabase

Confirmation for Destructive Operations

MongoDB Lens implements a token-based confirmation system for destructive operations:

1. First invocation: Returns a 4-digit confirmation token
2. Second invocation: Executes the operation if provided with the valid token

Tools that require confirmation include:

• drop-user, drop-index, drop-database, drop-collection
• delete-document, bulk-operations (when including delete operations)
• rename-collection (when the target collection exists)

To bypass confirmation, set:

CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS=true npx -y mongodb-lens@latest

Disabling Destructive Operations

To disable specific tools, add them to your configuration file:

{
  "disabled": {
    "tools": [
      "drop-user",
      "drop-index",
      "drop-database",
      "drop-collection",
      "delete-document",
      "bulk-operations",
      "rename-collection"
    ]
  }
}

Usage Examples

Basic Database Operations

• "List all databases"
• "What db am I currently using?"
• "Switch to the sample_mflix database"
• "Create a new db called test_db"

Collection Management

• "What collections are in the current database?"
• "Create user_logs collection"
• "Rename user_logs to system_logs"
• "Check the data consistency in the movies collection"

Querying Data

• "Count all docs in the movies collection"
• "Find the top 5 movies with the highest IMDB rating"
• "Show me aggregate data for movies grouped by decade"
• "List all unique countries where movies were produced"
• "Search for movies containing godfather in their title"

Schema Analysis

• "What's the schema structure of the movies collection?"
• "Compare users and comments schemas"
• "Generate a schema validator for the movies collection"
• "Analyze common query patterns for the movies collection"

Data Modification

• "Insert new movie document: {title: 'Example Movie', year: 2023}"
• "Update all movies from 1994 to add a 'classic' flag"
• "Delete all movies with zero ratings" (requires confirmation)

Performance & Index Management

• "Create an index on the title field in the movies collection"
• "Explain the execution plan for finding movies from 1995"
• "Get statistics for the current db"
• "Show collection stats for the movies collection"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mongodb-lens" '{"command":"npx","args":["-y","mongodb-lens@latest","mongodb://localhost:27017"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mongodb-lens": {
            "command": "npx",
            "args": [
                "-y",
                "mongodb-lens@latest",
                "mongodb://localhost:27017"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mongodb-lens": {
            "command": "npx",
            "args": [
                "-y",
                "mongodb-lens@latest",
                "mongodb://localhost:27017"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect