MongoDB Lens

MongoDB Lens is a local Model Context Protocol (MCP) server with full featured access to MongoDB databases using natural language via LLMs to perform queries, run aggregations, optimize performance, and more.

Contents

• Quick Start
• Features
• Installation
• Configuration
• Client Setup
• Tutorial
• Disclaimer

Quick Start

• Clone repository
• Install dependencies
• Configure MongoDB Lens
• Set up your MCP Client (e.g. Claude Desktop)
• Start exploring your MongoDB databases with natural language queries

Features

MongoDB Lens exposes the following capabilities through MCP:

• Resources
• Tools
• Prompts

Resources

• Collection metadata
• Collection statistics
• Collection validation rules
• Database listings
• Database users and roles
• Index information
• Replica set configuration
• Schema inference
• Server status and metrics
• Stored JavaScript functions

Tools

• aggregate-data: Execute aggregation pipelines
• analyze-schema: Automatically infer collection schemas
• bulk-operations: Perform multiple operations efficiently
• count-documents: Count documents matching specified criteria
• create-collection: Create new collections with custom options
• create-index: Create new indexes for performance optimization
• current-database: Show the current database context
• distinct-values: Extract unique values for any field
• drop-collection: Remove collections from the database
• explain-query: Analyze query execution plans
• export-data: Export query results in JSON or CSV format
• find-documents: Run queries with filters, projections, and sorting
• get-stats: Retrieve database or collection statistics
• list-collections: Explore collections in the current database
• list-databases: View all accessible MongoDB databases
• map-reduce: Run MapReduce operations for complex data processing
• modify-document: Insert, update, or delete specific documents
• rename-collection: Rename existing collections
• use-database: Switch to a specific database context
• validate-collection: Check for data inconsistencies

Prompts

• aggregation-builder: Step-by-step creation of aggregation pipelines
• backup-strategy: Customized backup and recovery recommendations
• data-modeling: Expert advice on MongoDB schema design for specific use cases
• index-recommendation: Get personalized index suggestions based on query patterns
• inspector-guide: Get help using MongoDB Lens with MCP Inspector
• migration-guide: Step-by-step MongoDB version migration plans
• mongo-shell: Generate MongoDB shell commands with explanations
• query-builder: Interactive guidance for constructing MongoDB queries
• query-optimizer: Optimization recommendations for slow queries
• schema-analysis: Detailed collection schema analysis with recommendations
• security-audit: Database security analysis and improvement recommendations

Installation

MongoDB Lens can run via Docker or Node.js.

Depending on your preference, follow the installation instructions below:

• Docker Installation
• Node.js Installation
• Installation Verification

Docker Installation

1. Navigate to the cloned repository directory:<br>
   cd /path/to/mongodb-lens
2. Build the Docker image:<br>
   docker build -t mongodb-lens .
3. Check the installation runs (tip: press <kbd>Ctrl</kbd>+<kbd>C</kbd> to exit):<br>
   # 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
4. Verify the server installation by sending a test message.

Node.js Installation

1. Navigate to the cloned repository directory:<br>
   cd /path/to/mongodb-lens
2. Ensure Node running (tip: use Volta):<br>$ node -v >= 22.*
3. Install Node.js dependencies:<br>
   npm ci
4. Start the server (tip: press <kbd>Ctrl</kbd>+<kbd>C</kbd> to exit):<br>
   # Using default connection string mongodb://localhost:27017 node mongodb-lens.js # Using custom connection string node mongodb-lens.js mongodb://your-connection-string
5. Verify the server installation by sending a test message.

Installation Verification

To verify the installation, paste and run the following jsonrpc message into the server's stdio:

The server should respond with a list of databases in your MongoDB instance, e.g.:<br>

MongoDB Lens is now installed and ready to accept MCP requests.

Configuration

• MongoDB Connection String
• Logging

Configuration: MongoDB Connection String

The server accepts a MongoDB connection string as its only argument:

Example URIs:

• Local connection: mongodb://localhost:27017
• Connection with credentials and DB name: mongodb://username:password@hostname:27017/mydatabase
• Connection with DB name and options: mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority

If no connection string is provided, the server will attempt to connect to MongoDB via local connection:

Configuration: Logging

To enable verbose server logging, set environment variable VERBOSE_LOGGING to true.

Example Node.js usage:

Example Docker usage:

Client Setup

• Claude Desktop
• MCP Inspector
• Other MCP Clients

Client Setup: Claude Desktop

To use MongoDB Lens with Claude Desktop:

1. Install Claude Desktop
2. Create and/or open 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:
   • Example Docker configuration:<br>
     { "mcpServers": { "mongodb-lens": { "command": "docker", "args": [ "run", "--rm", "-i", "--network=host", "-e", "VERBOSE_LOGGING=[true|false]", "mongodb-lens", "mongodb://your-connection-string" ] } } }
     • Replace mongodb://your-connection-string with your MongoDB connection string
     • Set VERBOSE_LOGGING to true for verbose MCP Server logs
   • Example Node.js configuration:<br>
     { "mcpServers": { "mongodb-lens": { "command": "/absolute/path/to/node", "args": [ "/absolute/path/to/mongodb-lens.js", "mongodb://your-connection-string" ], "env": { "VERBOSE_LOGGING": "<true|false>" } } } }
     • Replace /absolute/path/to/node with the full path to node
     • Replace /absolute/path/to/mongodb-lens.js with the full file path to mongodb-lens.js
     • Replace mongodb://your-connection-string with your MongoDB connection string
     • Set VERBOSE_LOGGING to true for verbose MCP Server logs
4. Restart Claude Desktop
5. Start a conversation with Claude about your MongoDB data
   • Claude will show a hammer icon indicating available tools
   • See example queries for conversation inspiration

Client Setup: MCP Inspector

MCP Inspector is a tool designed for testing and debugging MCP servers.

To use MongoDB Lens with MCP Inspector:

1. Navigate to the cloned repository directory:<br>
   cd /path/to/mongodb-lens
2. Run Inspector via npx:<br>
   npx @modelcontextprotocol/inspector node mongodb-lens.js mongodb://your-connection-string
3. Inspector starts a proxy server (default port: 3000) and web app (default port: 5173)
   • To change the default ports:<br>
     CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node mongodb-lens.js
4. Open Inspector web app: http://localhost:5173
5. Inspector should supports the full range of MongoDB Lens capabilities, including autocompletion for collection names and query fields.

For more, see: MCP Inspector

Client Setup: Other MCP Clients

MongoDB Lens can be used with any MCP-compatible client.

For more, see: MCP Documentation: Example Clients

Tutorial

This following tutorial guides you through setting up a MongoDB container with sample data, then using MongoDB Lens to interact with it through natural language queries:

• Setting Up Sample Data Container
• Importing Sample Data
• Connecting MongoDB Lens
• Example Queries

Tutorial: Setting Up Sample Data Container

[!IMPORTANT]<br> If you already have a Docker container running on port 27017, stop it before proceeding.

1. Initialise sample data container (requires Docker):<br>
   docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6
2. Verify the container is running without issue:<br>
   docker ps | grep mongodb-sampledata

Tutorial: Importing Sample Data

MongoDB provides several sample datasets, which we'll use to explore MongoDB Lens.

1. Download the sample datasets:
   curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive
2. Copy the sample datasets into your sample data container:<br>
   docker cp sampledata.archive mongodb-sampledata:/tmp/
3. Restore the sample data:<br>
   docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive

This will import several sample databases including:

• sample_airbnb: Airbnb listings and reviews
• sample_analytics: Customer and account data
• sample_geospatial: Geographic data
• sample_mflix: Movie data
• sample_restaurants: Restaurant data
• sample_supplies: Supply chain data
• sample_training: Training data for various applications
• sample_weatherdata: Weather measurements

Tutorial: Connecting MongoDB Lens

Download and install MongoDB Lens as per the Quick Start instructions.

Set your MCP Client to connect to MongoDB Lens with the connection string:

[!TIP]<br> As the default connection string is mongodb://localhost:27017, simply omit it from the client configuration.

For example, if using Claude Desktop set claude_desktop_config.json to:

Tutorial: Example Queries

With your MCP Client running and connected to MongoDB Lens, try these example queries that demonstrate the capabilities of the various tools, resources, and prompts available through MongoDB Lens:

• Example Queries: Basic Database Operations
• Example Queries: Movie Data Analysis
• Example Queries: Airbnb Data Exploration
• Example Queries: Weather Data Operations
• Example Queries: Bulk Operations & Data Modeling
• Example Queries: Administrative Operations

Example Queries: Basic Database Operations

• "List all available databases"<br> ^{➥ Uses list-databases tool}
• "What's the current database I'm connected to?"<br> ^{➥ Uses current-database tool}
• "Switch to the sample_mflix database"<br> ^{➥ Uses use-database tool}
• "What collections are available in this database?"<br> ^{➥ Uses list-collections tool}
• "Get statistics for the sample_mflix database"<br> ^{➥ Uses get-stats tool with database target}
• "Create the temp_collection collection, then drop it"<br> ^{➥ Uses create-collection & drop-collection tool}

Example Queries: Movie Data Analysis

• "Count how many movies are in the movies collection"<br> ^{➥ Uses count-documents tool}
• "Find the top 5 movies by IMDB rating with a runtime over 120 minutes"<br> ^{➥ Uses find-documents tool with sort and filter}
• "What's the schema of the movies collection?"<br> ^{➥ Uses analyze-schema tool}
• "Find distinct countries where movies were produced"<br> ^{➥ Uses distinct-values tool}
• "Create an index on the title field in the movies collection"<br> ^{➥ Uses create-index tool}
• "Why is my query for movies with over 1000 votes slow? Help me optimize it"<br> ^{➥ Uses query-optimizer prompt}
• "Run an explain on the query {year: 1995}"<br> ^{➥ Uses explain-query tool}
• "Build an aggregation pipeline to show the count of movies by decade and genre"<br> ^{➥ Uses aggregation-builder prompt}
• _"Execute this aggregation pipeline: [{$group: {id: {$floor: {$divide: ['$year', 10]}}, count: {$sum: 1}}}]"<br> ^{➥ Uses aggregate-data tool}
• "Update all movies from 1994 to add a 'classic' field set to true"<br> ^{➥ Uses modify-document tool with update operation}

Example Queries: Airbnb Data Exploration

• "Switch to sample_airbnb database"<br> ^{➥ Uses use-database tool}
• "Get collection statistics for the listingsAndReviews collection"<br> ^{➥ Uses get-stats tool with collection target}
• "What's the validation rules for the listingsAndReviews collection?"<br> ^{➥ Uses collection-validation resource}
• "Show me the indexes on the listingsAndReviews collection"<br> ^{➥ Uses collection-indexes resource}
• "Find listings with more than 5 bedrooms in Manhattan, limited to 10 results"<br> ^{➥ Uses find-documents tool}
• "Get distinct property types in the listings"<br> ^{➥ Uses distinct-values tool}
• "Help me create a query filter to find superhosts with pool amenities"<br> ^{➥ Uses query-builder prompt}
• "Export the top 20 highest-rated listings in Brooklyn as CSV with name, price, and rating"<br> ^{➥ Uses export-data tool}
• "Is my schema optimized for querying by neighborhood? Analyze and give recommendations"<br> ^{➥ Uses schema-analysis prompt}
• "Rename the reviews collection to guest_reviews"<br> ^{➥ Uses rename-collection tool}

Example Queries: Weather Data Operations

• "Switch to sample_weatherdata database"<br> ^{➥ Uses use-database tool}
• "What's in the schema of the data collection?"<br> ^{➥ Uses collection-schema resource}
• "Find the highest recorded temperatures with a callLetters of 'SHIP'"<br> ^{➥ Uses find-documents tool}
• "Validate the data collection for inconsistencies"<br> ^{➥ Uses validate-collection tool}
• "Insert a new weather record for today"<br> ^{➥ Uses modify-document tool with insert operation}
• "Create a new collection called weather_summary"<br> ^{➥ Uses create-collection tool}
• "Create index recommendation for queries that filter by callLetters and sort by date"<br> ^{➥ Uses index-recommendation prompt}
• "Show me how to write a MapReduce operation to get average temperatures by day"<br> ^{➥ Uses mongo-shell prompt}
• "Run this MapReduce to calculate average pressure by location"<br> ^{➥ Uses map-reduce tool}
• "Delete all weather readings below -50 degrees"<br> ^{➥ Uses modify-document tool with delete operation}

Example Queries: Bulk Operations & Data Modeling

• "Switch to sample_training database"<br> ^{➥ Uses use-database tool}
• "Execute a bulk operation to update multiple post documents to add 'edited' flags"<br> ^{➥ Uses bulk-operations tool}
• "How should I model a social media application in MongoDB?"<br> ^{➥ Uses data-modeling prompt}
• "Perform a bulk insertion of new product records in the supplies database"<br> ^{➥ Uses bulk-operations tool}
• "Show me how to use MongoDB Lens with the MCP Inspector"<br> ^{➥ Uses inspector-guide prompt}
• "What's the optimal data model for a multi-tenant SaaS application with heavy analytical queries?"<br> ^{➥ Uses data-modeling prompt}

Example Queries: Administrative Operations

• "Switch to the admin database"<br> ^{➥ Uses use-database tool}
• "Show me the server status"<br> ^{➥ Uses server-status resource}
• "Display the replica set configuration"<br> ^{➥ Uses replica-status resource}
• "List all users in the database"<br> ^{➥ Uses database-users resource}
• "Get any stored JavaScript functions"<br> ^{➥ Uses stored-functions resource}
• "Perform a security audit on my MongoDB deployment"<br> ^{➥ Uses security-audit prompt}
• "What's a good backup strategy for my MongoDB instance?"<br> ^{➥ Uses backup-strategy prompt}
• "How would I migrate from MongoDB 4.4 to 6.0?"<br> ^{➥ Uses migration-guide prompt}

Disclaimer

MongoDB Lens:

• is licensed under the MIT License.
• is not affiliated with or endorsed by MongoDB, Inc.
• is written with the assistance of AI and may contain errors.
• is intended for educational and experimental purposes only.
• is provided as-is with no warranty or support—use at your own risk.