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.

Quick Start
Features
Installation
Configuration
Client Setup
Data Protection
Tutorial
Test Suite
Disclaimer
Support

Quick Start

Install MongoDB Lens
Configure MongoDB Lens
Set up your MCP Client (e.g. Claude Desktop, Cursor, etc)
Explore your MongoDB databases with natural language queries

Tools

add-connection-alias: Add a new MongoDB connection alias
aggregate-data: Execute aggregation pipelines
analyze-query-patterns: Analyze live queries and suggest optimizations
analyze-schema: Automatically infer collection schemas
bulk-operations: Perform multiple operations efficiently (requires confirmation for destructive operations)
clear-cache: Clear memory caches to ensure fresh data
collation-query: Find documents with language-specific collation rules
compare-schemas: Compare schemas between two collections
connect-mongodb: Connect to a different MongoDB URI
connect-original: Connect back to the original MongoDB URI used at startup
count-documents: Count documents matching specified criteria
create-collection: Create new collections with custom options
create-database: Create a new database with option to switch to it
create-index: Create new indexes for performance optimization
create-timeseries: Create time series collections for temporal data
create-user: Create new database users with specific roles
current-database: Show the current database context
delete-document: Delete documents matching specified criteria (requires confirmation)
distinct-values: Extract unique values for any field
drop-collection: Remove collections from the database (requires confirmation)
drop-database: Drop a database (requires confirmation)
drop-index: Remove indexes from collections (requires confirmation)
drop-user: Remove database users (requires confirmation)
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
generate-schema-validator: Generate JSON Schema validators
geo-query: Perform geospatial queries with various operators
get-stats: Retrieve database or collection statistics
gridfs-operation: Manage large files with GridFS buckets
insert-document: Insert one or more documents into collections
list-collections: Explore collections in the current database
list-connections: View all available MongoDB connection aliases
list-databases: View all accessible databases
rename-collection: Rename existing collections (requires confirmation when dropping targets)
shard-status: View sharding configuration for databases and collections
text-search: Perform full-text search across text-indexed fields
transaction: Execute multiple operations in a single ACID transaction
update-document: Update documents matching specified criteria
use-database: Switch to a specific database context
validate-collection: Check for data inconsistencies
watch-changes: Monitor real-time changes to collections

Resources

collection-indexes: Index information for a collection
collection-schema: Schema information for a collection
collection-stats: Performance statistics for a collection
collection-validation: Validation rules for a collection
collections: List of collections in the current database
database-triggers: Database change streams and event triggers configuration
database-users: Database users and roles in the current database
databases: List of all accessible databases
performance-metrics: Real-time performance metrics and profiling data
replica-status: Replica set status and configuration
server-status: Server status information
stored-functions: Stored JavaScript functions in the current database

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
database-health-check: Comprehensive database health assessment and recommendations
index-recommendation: Get personalized index suggestions based on query patterns
migration-guide: Step-by-step MongoDB version migration plans
mongo-shell: Generate MongoDB shell commands with explanations
multi-tenant-design: Design MongoDB multi-tenant database architecture
query-builder: Interactive guidance for constructing MongoDB queries
query-optimizer: Optimization recommendations for slow queries
schema-analysis: Detailed collection schema analysis with recommendations
schema-versioning: Manage schema evolution in MongoDB applications
security-audit: Database security analysis and improvement recommendations
sql-to-mongodb: Convert SQL queries to MongoDB aggregation pipelines

Other Features

Overview
New Database Metadata

Other Features: Overview

MongoDB Lens includes numerous other features:

Config File: Custom configuration via ~/.mongodb-lens.[jsonc|json]
Env Var Overrides: Override config settings via process.env.CONFIG_*
Confirmation System: Two-step verification for destructive operations
Multiple Connections: Define and switch between named URI aliases
Component Disabling: Selectively disable tools, prompts or resources
Connection Resilience: Auto-reconnection with exponential backoff
Query Safeguards: Configurable limits and performance protections
Error Handling: Comprehensive JSONRPC error codes and messages
Schema Inference: Efficient schema analysis with intelligent sampling
Credential Protection: Connection string password obfuscation in logs
Memory Management: Auto-monitoring and cleanup for large operations
Smart Caching: Optimized caching for schema, indexes, fields and collections
Backwards Compatible: Support both modern and legacy MongoDB versions

Other Features: New Database Metadata

MongoDB Lens inserts a metadata collection into each database it creates.

This metadata collection stores a single document containing contextual information serving as a permanent record of the database's origin while ensuring the new and otherwise empty database persists in MongoDB's storage system.

Example metadata document

{
    "_id" : ObjectId("67d5284463788ec38aecee14"),
    "created" : {
        "timestamp" : ISODate("2025-03-15T07:12:04.705Z"),
        "tool" : "MongoDB Lens v5.0.7",
        "user" : "anonymous"
    },
    "mongodb" : {
        "version" : "3.6.23",
        "connectionInfo" : {
            "host" : "unknown",
            "readPreference" : "primary"
        }
    },
    "database" : {
        "name" : "example_database",
        "description" : "Created via MongoDB Lens"
    },
    "system" : {
        "hostname" : "unknown",
        "platform" : "darwin",
        "nodeVersion" : "v22.14.0"
    },
    "lens" : {
        "version" : "5.0.7",
        "startTimestamp" : ISODate("2025-03-15T07:10:06.084Z")
    }
}

Once you've added your own collections to your new database, you can safely remove the metadata collection via the drop-collection tool:

"Drop the new database's metadata collection"
^{➥ Uses drop-collection tool (with confirmation)}

Installation

MongoDB Lens can be installed and run in several ways:

NPX (Easiest)
Docker Hub
Node.js from Source
Docker from Source
Installation Verification
Older MongoDB Versions

Installation: NPX

[!NOTE]
NPX requires Node.js installed and running on your system (suggestion: use Volta).

The easiest way to run MongoDB Lens is using NPX.

First, ensure Node.js is installed:

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

[!TIP]
If you encounter permissions errors with npx try running npx clear-npx-cache prior to running npx -y mongodb-lens (this clears the cache and re-downloads the package).

Installation: Docker Hub

[!NOTE]
Docker Hub requires Docker installed and running on your system.

First, ensure Docker is installed:

docker --version # Ideally >= v27.x

Then, 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

Installation: Node.js from Source

[!NOTE]
Node.js from source requires Node.js installed and running on your system (suggestion: use Volta).

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```

Ensure Node.js is installed:

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

Install Node.js dependencies:
```
npm ci
```

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

Installation: Docker from Source

[!NOTE]
Docker from source requires Docker installed and running on your system.

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```
Ensure Docker is installed:
```
docker --version # Ideally >= v27.x
```
Build the Docker image:
```
docker build -t mongodb-lens .
```

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

Installation Verification

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

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

The server should respond with a list of databases in your MongoDB instance, for example:

{"result":{"contents":[{"uri":"mongodb://databases","text":"Databases (12):\n- admin (180.00 KB)\n- config (108.00 KB)\n- local (40.00 KB)\n- sample_airbnb (51.88 MB)\n- sample_analytics (9.46 MB)\n- sample_geospatial (980.00 KB)\n- sample_guides (40.00 KB)\n- sample_mflix (108.90 MB)\n- sample_restaurants (7.73 MB)\n- sample_supplies (968.00 KB)\n- sample_training (40.85 MB)\n- sample_weatherdata (2.69 MB)"}]},"jsonrpc":"2.0","id":1}

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

Installation: Older MongoDB Versions

If connecting to a MongoDB instance with a version < 4.0, the MongoDB Node.js driver used by the latest version of MongoDB Lens will not be compatible. Specifically, MongoDB Node.js driver versions 4.0.0 and above require MongoDB version 4.0 or higher.

To use MongoDB Lens with older MongoDB instances, you need to use a MongoDB Node.js driver version from the 3.x series (e.g. 3.7.4 which is compatible with MongoDB 3.6).

Older MongoDB Versions: Running from Source

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```

Modify package.json:

"dependencies": {
  ...
-  "mongodb": "^6.15.0",  // Or whatever newer version is listed
+  "mongodb": "^3.7.4",   // Or whatever 3.x version is compatible with your older MongoDB instance
  ...
}

Install Node.js dependencies:
```
npm install
```

Start MongoDB Lens:

node mongodb-lens.js mongodb://older-mongodb-instance

This will use the older driver version compatible with your MongoDB instance.

[!NOTE]
You may also need to revert this commit to add back useNewUrlParser and useUnifiedTopology MongoDB configuration options.

Older MongoDB Versions: Using NPX or Docker

If you prefer to use NPX or Docker, you'll need to use an older version of MongoDB Lens that was published with a compatible driver.

For example, MongoDB Lens 8.3.0 uses MongoDB Node.js driver 3.7.4 (see: package-lock.json).

To run an older version of MongoDB Lens using NPX, specify the version tag:

npx -y mongodb-lens@8.3.0

Similarly for Docker:

docker run --rm -i --network=host furey/mongodb-lens:8.3.0

Configuration

MongoDB Connection String
Config File
Config File Generation
Multiple MongoDB Connections
Environment Variable Overrides
Cross-Platform Environment Variables

Configuration: MongoDB Connection String

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

Example NPX usage:

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

MongoDB connection strings have the following format:

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

Example connection strings:

Local connection:
mongodb://localhost:27017
Connection to mydatabase with credentials from admin database:
mongodb://username:password@hostname:27017/mydatabase?authSource=admin
Connection to mydatabase with various other options:
mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority

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

Configuration: Config File

MongoDB Lens supports extensive customization via JSON configuration file.

[!NOTE]
The config file is optional. MongoDB Lens will run with default settings if no config file is provided.

[!TIP]
You only need to include the settings you want to customize in the config file. MongoDB Lens will use default settings for any omitted values.

[!TIP]
MongoDB Lens supports both .json and .jsonc (JSON with comments) config file formats.

Example configuration file

{
  "mongoUri": "mongodb://localhost:27017",         // Default MongoDB connection string or object of alias-URI pairs
  "connectionOptions": {
    "maxPoolSize": 20,                             // Maximum number of connections in the pool
    "retryWrites": false,                          // Whether to retry write operations
    "connectTimeoutMS": 30000,                     // Connection timeout in milliseconds
    "socketTimeoutMS": 360000,                     // Socket timeout in milliseconds
    "heartbeatFrequencyMS": 10000,                 // How often to ping servers for status
    "serverSelectionTimeoutMS": 30000              // Timeout for server selection
  },
  "defaultDbName": "admin",                        // Default database if not specified in URI
  "connection": {
    "maxRetries": 5,                               // Maximum number of initial connection attempts
    "maxRetryDelayMs": 30000,                      // Maximum delay between retries
    "reconnectionRetries": 10,                     // Maximum reconnection attempts if connection lost
    "initialRetryDelayMs": 1000                    // Initial delay between retries
  },
  "disabled": {
    "tools": [],                                   // Array of tools to disable or true to disable all
    "prompts": [],                                 // Array of prompts to disable or true to disable all
    "resources": []                                // Array of resources to disable or true to disable all
  },
  "enabled": {
    "tools": true,                                 // Array of tools to enable or true to enable all
    "prompts": true,                               // Array of prompts to enable or true to enable all
    "resources": true                              // Array of resources to enable or true to enable all
  },
  "cacheTTL": {
    "stats": 15000,                                // Stats cache lifetime in milliseconds
    "fields": 30000,                               // Fields cache lifetime in milliseconds
    "schemas": 60000,                              // Schema cache lifetime in milliseconds
    "indexes": 120000,                             // Index cache lifetime in milliseconds
    "collections": 30000,                          // Collections list cache lifetime in milliseconds
    "serverStatus": 20000                          // Server status cache lifetime in milliseconds
  },
  "enabledCaches": [                               // List of caches to enable
    "stats",                                       // Statistics cache
    "fields",                                      // Collection fields cache
    "schemas",                                     // Collection schemas cache
    "indexes",                                     // Collection indexes cache
    "collections",                                 // Database collections cache
    "serverStatus"                                 // MongoDB server status cache
  ],
  "memory": {
    "enableGC": true,                              // Whether to enable garbage collection
    "warningThresholdMB": 1500,                    // Memory threshold for warnings
    "criticalThresholdMB": 2000                    // Memory threshold for cache clearing
  },
  "logLevel": "info",                              // Log level (info or verbose)
  "disableDestructiveOperationTokens": false,      // Whether to skip confirmation for destructive ops
  "watchdogIntervalMs": 30000,                     // Interval for connection monitoring
  "defaults": {
    "slowMs": 100,                                 // Threshold for slow query detection
    "queryLimit": 10,                              // Default limit for query results
    "allowDiskUse": true,                          // Allow operations to use disk for large datasets
    "schemaSampleSize": 100,                       // Sample size for schema inference
    "aggregationBatchSize": 50                     // Batch size for aggregation operations
  },
  "security": {
    "tokenLength": 4,                              // Length of confirmation tokens
    "tokenExpirationMinutes": 5,                   // Expiration time for tokens
    "strictDatabaseNameValidation": true           // Enforce strict database name validation
  },
  "tools": {
    "transaction": {
      "readConcern": "snapshot",                   // Read concern level for transactions
      "writeConcern": {
        "w": "majority"                            // Write concern for transactions
      }
    },
    "bulkOperations": {
      "ordered": true                              // Whether bulk operations execute in order
    },
    "export": {
      "defaultLimit": -1,                          // Default limit for exports (-1 = no limit)
      "defaultFormat": "json"                      // Default export format (json or csv)
    },
    "watchChanges": {
      "maxDurationSeconds": 60,                    // Maximum duration for change streams
      "defaultDurationSeconds": 10                 // Default duration for change streams
    },
    "queryAnalysis": {
      "defaultDurationSeconds": 10                 // Default duration for query analysis
    }
  }
}

By default, MongoDB Lens looks for the config file at:

~/.mongodb-lens.jsonc first, then falls back to
~/.mongodb-lens.json if the former doesn't exist

To customize the config file path, set the environment variable CONFIG_PATH to the desired file path.

Example NPX usage:

CONFIG_PATH='/path/to/config.json' npx -y mongodb-lens@latest

Example Docker Hub usage:

docker run --rm -i --network=host --pull=always -v /path/to/config.json:/root/.mongodb-lens.json furey/mongodb-lens

Configuration: Config File Generation

You can generate a configuration file automatically using the config:create script:

# NPX Usage (recommended)
npx -y mongodb-lens@latest config:create

# Node.js Usage
npm run config:create

# Force overwrite existing files
npx -y mongodb-lens@latest config:create -- --force
npm run config:create -- --force

This script extracts the example configuration file above and saves it to: ~/.mongodb-lens.jsonc

Config File Generation: Custom Path

You can specify a custom output location using the CONFIG_PATH environment variable.

If CONFIG_PATH has no file extension, it's treated as a directory and .mongodb-lens.jsonc is appended
If CONFIG_PATH ends with .json (not .jsonc) comments are removed from the generated file

Example NPX usage:

# With custom path
CONFIG_PATH=/path/to/config.jsonc npx -y mongodb-lens@latest config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory npx -y mongodb-lens@latest config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json npx -y mongodb-lens@latest config:create

Example Node.js usage:

# With custom path
CONFIG_PATH=/path/to/config.jsonc node mongodb-lens.js config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory node mongodb-lens.js config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json node mongodb-lens.js config:create

Configuration: Multiple MongoDB Connections

MongoDB Lens supports multiple MongoDB URIs with aliases in your config file, allowing you to easily switch between different MongoDB instances using simple names.

To configure multiple connections, set the mongoUri config setting to an object with alias-URI pairs:

{
  "mongoUri": {
    "main": "mongodb://localhost:27017",
    "backup": "mongodb://localhost:27018",
    "atlas": "mongodb+srv://username:password@cluster.mongodb.net/mydb"
  }
}

With this configuration:

The first URI in the list (e.g. main) becomes the default connection at startup
You can switch connections using natural language: "Connect to backup" or "Connect to atlas"
The original syntax still works: "Connect to mongodb://localhost:27018"
The list-connections tool shows all available connection aliases

[!NOTE]
When using the command-line argument to specify a connection, you can use either a full MongoDB URI or an alias defined in your configuration file.

[!TIP]
To add connection aliases at runtime, use the add-connection-alias tool.

Configuration: Environment Variable Overrides

MongoDB Lens supports environment variable overrides for configuration settings.

Environment variables take precedence over config file settings.

Config environment variables follow the naming pattern:

CONFIG_[SETTING PATH, SNAKE CASED, UPPERCASED]

Example overrides:

Config Setting	Environment Variable Override
`mongoUri`	`CONFIG_MONGO_URI`
`logLevel`	`CONFIG_LOG_LEVEL`
`defaultDbName`	`CONFIG_DEFAULT_DB_NAME`
`defaults.queryLimit`	`CONFIG_DEFAULTS_QUERY_LIMIT`
`tools.export.defaultFormat`	`CONFIG_TOOLS_EXPORT_DEFAULT_FORMAT`
`connectionOptions.maxPoolSize`	`CONFIG_CONNECTION_OPTIONS_MAX_POOL_SIZE`
`connection.reconnectionRetries`	`CONFIG_CONNECTION_RECONNECTION_RETRIES`

For environment variable values:

For boolean settings, use string values 'true' or 'false'.
For numeric settings, use string representations.
For nested objects or arrays, use JSON strings.

Example NPX usage:

CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

Example Docker Hub usage:

docker run --rm -i --network=host --pull=always -e CONFIG_DEFAULTS_QUERY_LIMIT='25' furey/mongodb-lens

Configuration: Cross-Platform Environment Variables

For consistent environment variable usage across Windows, macOS, and Linux, consider using cross-env:

Install cross-env globally:

# Using NPM
npm install -g cross-env

# Using Volta (see: https://volta.sh)
volta install cross-env

Prefix any NPX or Node.js environment variables in this document's examples:

# Example NPX usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

# Example Node.js usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' node mongodb-lens.js

Client Setup

Claude Desktop
MCP Inspector
Other MCP Clients

Client Setup: Claude Desktop

To use MongoDB Lens with Claude Desktop:

Install Claude Desktop
Open claude_desktop_config.json (create if it doesn't exist):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the MongoDB Lens server configuration as per configuration options
Restart Claude Desktop
Start a conversation with Claude about your MongoDB data

Claude Desktop Configuration Options

Option 1: NPX (Recommended)
Option 2: Docker Hub Image
Option 3: Local Node.js Installation
Option 4: Local Docker Image

For each option:

Replace mongodb://your-connection-string with your MongoDB connection string or omit it to use the default mongodb://localhost:27017.
To use a custom config file, set CONFIG_PATH environment variable.

To include environment variables:

For NPX or Node.js add "env": {} with key-value pairs, for example:

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

For Docker add -e flags, for example:

"command": "docker",
"args": [
  "run", "--rm", "-i",
  "--network=host",
  "--pull=always",
  "-e", "CONFIG_LOG_LEVEL=verbose",
  "furey/mongodb-lens",
  "mongodb://your-connection-string"
]

Option 1: NPX (Recommended)

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

Option 2: Docker Hub Image

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "--pull=always",
        "furey/mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Option 3: Local Node.js Installation

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/node",
      "args": [
        "/path/to/mongodb-lens.js",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Option 4: Local Docker Image

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Client Setup: MCP Inspector

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

[!NOTE]
MCP Inspector starts a proxy server on port 3000 and web client on port 5173.

Example NPX usage:

Run MCP Inspector:

# Using default connection string mongodb://localhost:27017
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

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

# Using custom ports
SERVER_PORT=1234 CLIENT_PORT=5678 npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

Open MCP Inspector: http://localhost:5173

MCP Inspector should support 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 should be usable with any MCP-compatible client.

For more, see: MCP Documentation: Example Clients

Data Protection

To protect your data while using MongoDB Lens, consider the following:

Read-Only User Accounts
Working with Database Backups
Data Flow Considerations
Confirmation for Destructive Operations
Disabling Destructive Operations

Data Protection: Read-Only User Accounts

When connecting MongoDB Lens to your database, the permissions granted to the user in the MongoDB connection string dictate what actions can be performed. When the use case fits, a read-only user can prevent unintended writes or deletes, ensuring MongoDB Lens can query data but not alter it.

To set this up, create a user with the read role scoped to the database(s) you're targeting. In MongoDB shell, you'd run something like:

use admin

db.createUser({
  user: 'readonly',
  pwd: 'eXaMpLePaSsWoRd',
  roles: [{ role: 'read', db: 'mydatabase' }]
})

Then, apply those credentials to your MongoDB connection string:

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

Using read-only credentials is a simple yet effective way to enforce security boundaries, especially when you're poking around schemas or running ad-hoc queries.

Data Protection: Working with Database Backups

When working with MongoDB Lens, consider connecting to a backup copy of your data hosted on a separate MongoDB instance.

Start by generating the backup with mongodump. Next, spin up a fresh MongoDB instance (e.g. on a different port like 27018) and restore the backup there using mongorestore. Once it's running, point MongoDB Lens to the backup instance's connection string (e.g. mongodb://localhost:27018/mydatabase).

This approach gives you a sandbox to test complex or destructive operations against without risking accidental corruption of your live data.

Data Protection: Data Flow Considerations

How Your Data Flows Through the System
Protecting Sensitive Data with Projection
Connection Aliases and Passwords
Local Setup for Maximum Safety

Data Flow Considerations: How Your Data Flows Through the System

When using an MCP Server with a remote LLM provider (such as Anthropic via Claude Desktop) understanding how your data flows through the system is key to protecting sensitive information from unintended exposure.

When you send a MongoDB related query through your MCP client, here’s what happens:

[!NOTE]
While this example uses a local MongoDB instance, the same principles apply to remote MongoDB instances.

sequenceDiagram
    actor User
    box Local Machine #d4f1f9
        participant Client as MCP Client
        participant Lens as MongoDB Lens
        participant MongoDB as MongoDB Instance
    end
    box Remote Server #ffe6cc
        participant LLM as Remote LLM Provider
    end

    User->>Client: 1. Submit request<br>"Show me all users older than 30"
    Client->>LLM: 2. User request + available tools
    Note over LLM: Interprets request<br>Chooses appropriate tool
    LLM->>Client: 3. Tool selection (find-documents)
    Client->>Lens: 4. Tool run with parameters
    Lens->>MongoDB: 5. Database query
    MongoDB-->>Lens: 6. Database results
    Lens-->>Client: 7. Tool results (formatted data)
    Client->>LLM: 8. Tool results
    Note over LLM: Processes results<br>Formats response
    LLM-->>Client: 9. Processed response
    Client-->>User: 10. Final answer

You submit a request
^{➥ e.g. "Show me all users older than 30"}
Your client sends the request to the remote LLM
^{➥ The LLM provider receives your exact words along with a list of available MCP tools and their parameters.}
The remote LLM interprets your request
^{➥ It determines your intent and instructs the client to use a specific MCP tool with appropriate parameters.}
The client asks MongoDB Lens to run the tool
^{➥ This occurs locally on your machine via stdio.}
MongoDB Lens queries your MongoDB database
MongoDB Lens retrieves your MongoDB query results
MongoDB Lens sends the data back to the client
^{➥ The client receives results formatted by MongoDB Lens.}
The client forwards the data to the remote LLM
^{➥ The LLM provider sees the exact data returned by MongoDB Lens.}
The remote LLM processes the data
^{➥ It may summarize or format the results further.}
The remote LLM sends the final response to the client
^{➥ The client displays the answer to you.}

The remote LLM provider sees both your original request and the full response from MongoDB Lens. If your database includes sensitive fields (e.g. passwords, personal details, etc) this data could be unintentionally transmitted to the remote provider unless you take precautions.

Data Flow Considerations: Protecting Sensitive Data with Projection

To prevent sensitive data from being sent to the remote LLM provider, use the concept of projection when using tools like find-documents, aggregate-data, or export-data. Projection allows you to specify which fields to include or exclude in query results, ensuring sensitive information stays local.

Example projection usage:

"Show me all users older than 30, but use projection to hide their passwords."
^{➥ Uses find-documents tool with projection}

Data Flow Considerations: Connection Aliases and Passwords

When adding new connection aliases using the add-connection-alias tool, avoid added aliases to URIs that contain passwords if you're using a remote LLM provider. Since your request is sent to the LLM, any passwords in the URI could be exposed. Instead, define aliases with passwords in the MongoDB Lens config file, where they remain local and are not transmitted to the LLM.

Data Flow Considerations: Local Setup for Maximum Safety

While outside the scope of this document, for the highest level of data privacy, consider using a local MCP client paired with a locally hosted LLM model. This approach keeps all requests and data within your local environment, eliminating the risk of sensitive information being sent to a remote provider.

Data Protection: Confirmation for Destructive Operations

MongoDB Lens implements a token-based confirmation system for potentially destructive operations, requiring a two-step process to execute tools that may otherwise result in unchecked data loss:

First tool invocation: Returns a 4-digit confirmation token that expires after 5 minutes
Second tool invocation: Executes the operation if provided with the valid token

For an example of the confirmation process, see: Working with Confirmation Protection

Tools that require confirmation include:

drop-user: Remove a database user
drop-index: Remove an index (potential performance impact)
drop-database: Permanently delete a database
drop-collection: Delete a collection and all its documents
delete-document: Delete one or multiple documents
bulk-operations: When including delete operations
rename-collection: When the target collection exists and will be dropped

This protection mechanism aims to prevent accidental data loss from typos and unintended commands. It's a safety net ensuring you're aware of the consequences before proceeding with potentially harmful actions.

[!NOTE]
If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to bypass confirmation and perform destructive operations immediately.

Bypassing Confirmation for Destructive Operations

You might want to bypass the token confirmation system.

Set the environment variable CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS to true to execute destructive operations immediately without confirmation:

# Using NPX
CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS=true npx -y mongodb-lens@latest

# Using Docker
docker run --rm -i --network=host --pull=always -e CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS='true' furey/mongodb-lens

[!WARNING]
Disabling confirmation tokens removes an important safety mechanism. It's strongly recommended to only use this option in controlled environments where data loss is acceptable, such as development or testing. Disable at your own risk.

Data Protection: Disabling Destructive Operations

Disabling Tools
High-Risk Tools
Medium-Risk Tools
Read-Only Configuration
Selective Component Enabling

Disabling Tools

MongoDB Lens includes several tools that can modify or delete data. To disable specific tools, add them to the disabled.tools array in your configuration file:

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

[!NOTE]
Resources and prompts can also be disabled via disabled.resources and disabled.prompts settings.

High-Risk Tools

These tools can cause immediate data loss and should be considered for disabling in sensitive environments:

drop-user: Removes database users and their access permissions
drop-index: Removes indexes (can impact query performance)
drop-database: Permanently deletes entire databases
drop-collection: Permanently deletes collections and all their documents
delete-document: Removes documents matching specified criteria
bulk-operations: Can perform batch deletions when configured to do so
rename-collection: Can overwrite existing collections when using the drop target option

Medium-Risk Tools

These tools can modify data but typically don't cause immediate data loss:

create-user: Creates users with permissions that could enable further changes
transaction: Executes multiple operations in a transaction (potential for complex changes)
update-document: Updates documents which could overwrite existing data

Read-Only Configuration

For a complete read-only configuration, disable all potentially destructive tools:

{
  "disabled": {
    "tools": [
      "drop-user",
      "drop-index",
      "create-user",
      "transaction",
      "create-index",
      "drop-database",
      "drop-collection",
      "insert-document",
      "update-document",
      "delete-document",
      "bulk-operations",
      "create-database",
      "gridfs-operation",
      "create-collection",
      "rename-collection",
      "create-timeseries"
    ]
  }
}

This configuration allows MongoDB Lens to query and analyze data while preventing any modifications, providing multiple layers of protection against accidental data loss.

Selective Component Enabling

In addition to disabling components, specify exactly which components should be enabled (implicitly disabling all others) using the enabled settings in your configuration file:

{
  "enabled": {
    "tools": [
      "use-database",
      "find-documents",
      "count-documents",
      "aggregate-data"
    ]
  },
  "disabled": {
    "resources": true,
    "prompts": true
  }
}

[!IMPORTANT]
If a component appears in both enabled and disabled lists, the enabled setting takes precedence.

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:

Start Sample Data Container
Import Sample Data
Connect MongoDB Lens
Example Queries
Working With Confirmation Protection

Tutorial: 1. Start Sample Data Container

[!NOTE]
This tutorial assumes you have Docker installed and running on your system.

[!IMPORTANT]
If Docker is already running a container on port 27017, stop it before proceeding.

Initialise the sample data container:

docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6

Verify the container is running without issue:
```
docker ps | grep mongodb-sampledata
```

Tutorial: 2. Import Sample Data

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

Download the sample datasets:

curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive

Copy the sample datasets into your sample data container:
```
docker cp sampledata.archive mongodb-sampledata:/tmp/
```

Import the sample datasets into MongoDB:

docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive

This will import several databases:

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: 3. Connect MongoDB Lens

Install MongoDB Lens as per the Quick Start instructions.

Set your MCP Client to connect to MongoDB Lens via: mongodb://localhost:27017

[!TIP]
Omitting the connection string from your MCP Client configuration will default the connection string to mongodb://localhost:27017.

Example Claude Desktop configuration:

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

Tutorial: 4. Example Queries

With your MCP Client running and connected to MongoDB Lens, try the following example queries:

Example Queries: Basic Database Operations
Example Queries: Collection Management
Example Queries: User Management
Example Queries: Querying Data
Example Queries: Schema Analysis
Example Queries: Data Modification
Example Queries: Performance & Index Management
Example Queries: Geospatial & Special Operations
Example Queries: Export, Administrative & Other Features
Example Queries: Connection Management

Example Queries: Basic Database Operations

"List all databases"
^{➥ Uses list-databases tool}
"What db am I currently using?"
^{➥ Uses current-database tool}
"Switch to the sample_mflix database"
^{➥ Uses use-database tool}
"Create a new db called test_db"
^{➥ Uses create-database tool}
"Create another db called analytics_db and switch to it"
^{➥ Uses create-database tool with switch=true}
"Drop test_db"
^{➥ Uses drop-database tool (with confirmation)}

Example Queries: Collection Management

"What collections are in the current database?"
^{➥ Uses list-collections tool}
"Create user_logs collection"
^{➥ Uses create-collection tool}
"Rename user_logs to system_logs"
^{➥ Uses rename-collection tool}
"Drop system_logs"
^{➥ Uses drop-collection tool (with confirmation)}
"Check the data consistency in the movies collection"
^{➥ Uses validate-collection tool}

Example Queries: User Management

"Create a read-only user for analytics"
^{➥ Uses create-user tool}
"Drop the inactive_user account"
^{➥ Uses drop-user tool (with confirmation)}

Example Queries: Querying Data

"Count all docs in the movies collection"
^{➥ Uses count-documents tool}
"Find the top 5 movies with the highest IMDB rating"
^{➥ Uses find-documents tool}
"Show me aggregate data for movies grouped by decade"
^{➥ Uses aggregate-data tool}
"List all unique countries where movies were produced"
^{➥ Uses distinct-values tool}
"Search for movies containing godfather in their title"
^{➥ Uses text-search tool}
"Find German users with last name müller using proper collation"
^{➥ Uses collation-query tool}

Example Queries: Schema Analysis

"What's the schema structure of the movies collection?"
^{➥ Uses analyze-schema tool}
"Compare users and comments schemas"
^{➥ Uses compare-schemas tool}
"Generate a schema validator for the movies collection"
^{➥ Uses generate-schema-validator tool}
"Analyze common query patterns for the movies collection"
^{➥ Uses analyze-query-patterns tool}

Example Queries: Data Modification

"Insert new movie document: <your field data>"
^{➥ Uses insert-document tool}
"Update all movies from 1994 to add a 'classic' flag"
^{➥ Uses update-document tool}
"Delete all movies with zero ratings"
^{➥ Uses delete-document tool (with confirmation)}
"Run these bulk operations on the movies collection: <your JSON data>"
^{➥ Uses bulk-operations tool}

[!TIP]
For specialized MongoDB operations (like array operations, bitwise operations, or other complex updates), use MongoDB's native operators via the update-document tool's update and options parameters.

Example Queries: Performance & Index Management

"Create an index on the title field in the movies collection"
^{➥ Uses create-index tool}
"Drop the ratings_idx index"
^{➥ Uses drop-index tool (with confirmation)}
"Explain the execution plan for finding movies from 1995"
^{➥ Uses explain-query tool}
"Get statistics for the current db"
^{➥ Uses get-stats tool with target=database}
"Show collection stats for the movies collection"
^{➥ Uses get-stats tool with target=collection}

Example Queries: Geospatial & Special Operations

"Switch to sample_geospatial db, then find all shipwrecks within 10km of coordinates [-80.12, 26.46]"
^{➥ Uses geo-query tool}
"Switch to sample_analytics db, then execute a transaction to move funds between accounts: <account ids>"
^{➥ Uses transaction tool}
"Create a time series collection for sensor readings"
^{➥ Uses create-timeseries tool}
"Watch for changes in the users collection for 30 seconds"
^{➥ Uses watch-changes tool}
"List all files in the images GridFS bucket"
^{➥ Uses gridfs-operation tool with operation=list}

Example Queries: Export, Administrative & Other Features

"Switch to sample_mflix db, then export the top 20 movies based on 'tomatoes.critic.rating' as a CSV with title, year and rating fields (output in a single code block)"
^{➥ Uses export-data tool}
"Switch to sample_analytics db, then check its sharding status"
^{➥ Uses shard-status tool}
"Clear the collections cache"
^{➥ Uses clear-cache tool with target=collections}
"Clear all caches"
^{➥ Uses clear-cache tool}
"Switch to sample_weatherdata db then generate an interactive report on its current state"
^{➥ Uses numerous tools}

Example Queries: Connection Management

"Connect to mongodb://localhost:27018"
^{➥ Uses connect-mongodb tool}
"Connect to mongodb+srv://username:password@cluster.mongodb.net/mydb"
^{➥ Uses connect-mongodb tool}
"Connect back to the original mongodb instance"
^{➥ Uses connect-original tool}
"Connect to replica set without validating the connection: <replica set details>"
^{➥ Uses connect-mongodb tool with validateConnection=false}
"Add connection alias 'prod' for mongodb://username:password@prod-server:27017/mydb"
^{➥ Uses add-connection-alias tool}

Tutorial: 5. Working With Confirmation Protection

MongoDB Lens includes a safety mechanism for potentially destructive operations. Here's how it works in practice:

Request to drop a collection:

"Drop the collection named test_collection"

MongoDB Lens responds with a warning and confirmation token:

⚠️ DESTRUCTIVE OPERATION WARNING ⚠️

You've requested to drop the collection 'test_collection'.

This operation is irreversible and will permanently delete all data in this collection.

To confirm, you must type the 4-digit confirmation code EXACTLY as shown below:

Confirmation code: 9876

This code will expire in 5 minutes for security purposes.

Confirm the operation by submitting the confirmation token:
```
"9876"
```

MongoDB Lens executes the operation:

Collection 'test_collection' has been permanently deleted.

This two-step process prevents accidental data loss by requiring explicit confirmation.

[!NOTE]
If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to bypass confirmation and perform destructive operations immediately.

Test Suite

MongoDB Lens includes a test suite to verify functionality across tools, resources, and prompts.

Running Tests
Command Line Options
Examples

Test Suite: Running Tests

The test suite requires a CONFIG_MONGO_URI environment variable which can be set to:

a MongoDB connection string (e.g. mongodb://localhost:27017)
mongodb-memory-server (for in-memory testing)

# Run Tests with MongoDB Connection String
CONFIG_MONGO_URI=mongodb://localhost:27017 node mongodb-lens.test.js

# Run Tests with In-Memory MongoDB (requires mongodb-memory-server)
CONFIG_MONGO_URI=mongodb-memory-server node mongodb-lens.test.js

For convenience, the following scripts are available for running tests:

npm test                        # Fails if no CONFIG_MONGO_URI provided
npm run test:localhost          # Uses mongodb://localhost:27017
npm run test:localhost:verbose  # Runs with DEBUG=true for verbose output
npm run test:in-memory          # Uses mongodb-memory-server
npm run test:in-memory:verbose  # Runs with DEBUG=true for verbose output

[!NOTE]
The test suite creates temporary databases and collections that are cleaned up after test completion.

Test Suite: Command Line Options

Option	Description
`--list`	List all available tests without running them
`--test=<n>`	Run specific test(s) by name (comma-separated)
`--group=<n>`	Run all tests in specific group(s) (comma-separated)
`--pattern=<glob>`	Run tests matching pattern(s) (comma-separated)

Test Suite: Examples

# List All Available Tests
npm test -- --list

# Run Only Connection-Related Tests (:27017)
npm run test:localhost -- --group=Connection\ Tools

# Test Specific Database Operations (In-Memory)
npm run test:in-memory -- --test=create-database\ Tool,drop-database\ Tool

# Test All Document-Related Tools (:27017)
npm run test:localhost -- --pattern=document

# Run Resource Tests Only (In-Memory)
npm run test:in-memory -- --group=Resources

# Run Specific Tests Only (In-Memory)
npm run test:in-memory -- --test=aggregate-data\ Tool,find-documents\ Tool

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—please use at your own risk.

Support

If you've found MongoDB Lens helpful consider supporting my work through:

Buy Me a Coffee | GitHub Sponsorship

Contributions help me continue developing and improving this tool, allowing me to dedicate more time to add new features and ensuring it remains a valuable resource for the community.

MongoDB Lens

Quick Start
Features
Installation
Configuration
Client Setup
Data Protection
Tutorial
Test Suite
Disclaimer
Support

Quick Start

Install MongoDB Lens
Configure MongoDB Lens
Set up your MCP Client (e.g. Claude Desktop, Cursor, etc)
Explore your MongoDB databases with natural language queries

Features

Tools
Resources
Prompts
Other

Tools

add-connection-alias: Add a new MongoDB connection alias
aggregate-data: Execute aggregation pipelines
analyze-query-patterns: Analyze live queries and suggest optimizations
analyze-schema: Automatically infer collection schemas
bulk-operations: Perform multiple operations efficiently (requires confirmation for destructive operations)
clear-cache: Clear memory caches to ensure fresh data
collation-query: Find documents with language-specific collation rules
compare-schemas: Compare schemas between two collections
connect-mongodb: Connect to a different MongoDB URI
connect-original: Connect back to the original MongoDB URI used at startup
count-documents: Count documents matching specified criteria
create-collection: Create new collections with custom options
create-database: Create a new database with option to switch to it
create-index: Create new indexes for performance optimization
create-timeseries: Create time series collections for temporal data
create-user: Create new database users with specific roles
current-database: Show the current database context
delete-document: Delete documents matching specified criteria (requires confirmation)
distinct-values: Extract unique values for any field
drop-collection: Remove collections from the database (requires confirmation)
drop-database: Drop a database (requires confirmation)
drop-index: Remove indexes from collections (requires confirmation)
drop-user: Remove database users (requires confirmation)
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
generate-schema-validator: Generate JSON Schema validators
geo-query: Perform geospatial queries with various operators
get-stats: Retrieve database or collection statistics
gridfs-operation: Manage large files with GridFS buckets
insert-document: Insert one or more documents into collections
list-collections: Explore collections in the current database
list-connections: View all available MongoDB connection aliases
list-databases: View all accessible databases
rename-collection: Rename existing collections (requires confirmation when dropping targets)
shard-status: View sharding configuration for databases and collections
text-search: Perform full-text search across text-indexed fields
transaction: Execute multiple operations in a single ACID transaction
update-document: Update documents matching specified criteria
use-database: Switch to a specific database context
validate-collection: Check for data inconsistencies
watch-changes: Monitor real-time changes to collections

Resources

collection-indexes: Index information for a collection
collection-schema: Schema information for a collection
collection-stats: Performance statistics for a collection
collection-validation: Validation rules for a collection
collections: List of collections in the current database
database-triggers: Database change streams and event triggers configuration
database-users: Database users and roles in the current database
databases: List of all accessible databases
performance-metrics: Real-time performance metrics and profiling data
replica-status: Replica set status and configuration
server-status: Server status information
stored-functions: Stored JavaScript functions in the current database

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
database-health-check: Comprehensive database health assessment and recommendations
index-recommendation: Get personalized index suggestions based on query patterns
migration-guide: Step-by-step MongoDB version migration plans
mongo-shell: Generate MongoDB shell commands with explanations
multi-tenant-design: Design MongoDB multi-tenant database architecture
query-builder: Interactive guidance for constructing MongoDB queries
query-optimizer: Optimization recommendations for slow queries
schema-analysis: Detailed collection schema analysis with recommendations
schema-versioning: Manage schema evolution in MongoDB applications
security-audit: Database security analysis and improvement recommendations
sql-to-mongodb: Convert SQL queries to MongoDB aggregation pipelines

Other Features

Overview
New Database Metadata

Other Features: Overview

MongoDB Lens includes numerous other features:

Config File: Custom configuration via ~/.mongodb-lens.[jsonc|json]
Env Var Overrides: Override config settings via process.env.CONFIG_*
Confirmation System: Two-step verification for destructive operations
Multiple Connections: Define and switch between named URI aliases
Component Disabling: Selectively disable tools, prompts or resources
Connection Resilience: Auto-reconnection with exponential backoff
Query Safeguards: Configurable limits and performance protections
Error Handling: Comprehensive JSONRPC error codes and messages
Schema Inference: Efficient schema analysis with intelligent sampling
Credential Protection: Connection string password obfuscation in logs
Memory Management: Auto-monitoring and cleanup for large operations
Smart Caching: Optimized caching for schema, indexes, fields and collections
Backwards Compatible: Support both modern and legacy MongoDB versions

Other Features: New Database Metadata

MongoDB Lens inserts a metadata collection into each database it creates.

Example metadata document

{
    "_id" : ObjectId("67d5284463788ec38aecee14"),
    "created" : {
        "timestamp" : ISODate("2025-03-15T07:12:04.705Z"),
        "tool" : "MongoDB Lens v5.0.7",
        "user" : "anonymous"
    },
    "mongodb" : {
        "version" : "3.6.23",
        "connectionInfo" : {
            "host" : "unknown",
            "readPreference" : "primary"
        }
    },
    "database" : {
        "name" : "example_database",
        "description" : "Created via MongoDB Lens"
    },
    "system" : {
        "hostname" : "unknown",
        "platform" : "darwin",
        "nodeVersion" : "v22.14.0"
    },
    "lens" : {
        "version" : "5.0.7",
        "startTimestamp" : ISODate("2025-03-15T07:10:06.084Z")
    }
}

Once you've added your own collections to your new database, you can safely remove the metadata collection via the drop-collection tool:

"Drop the new database's metadata collection"
^{➥ Uses drop-collection tool (with confirmation)}

Installation

MongoDB Lens can be installed and run in several ways:

NPX (Easiest)
Docker Hub
Node.js from Source
Docker from Source
Installation Verification
Older MongoDB Versions

Installation: NPX

[!NOTE]
NPX requires Node.js installed and running on your system (suggestion: use Volta).

The easiest way to run MongoDB Lens is using NPX.

First, ensure Node.js is installed:

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

[!TIP]
If you encounter permissions errors with npx try running npx clear-npx-cache prior to running npx -y mongodb-lens (this clears the cache and re-downloads the package).

Installation: Docker Hub

[!NOTE]
Docker Hub requires Docker installed and running on your system.

First, ensure Docker is installed:

docker --version # Ideally >= v27.x

Then, 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

Installation: Node.js from Source

[!NOTE]
Node.js from source requires Node.js installed and running on your system (suggestion: use Volta).

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```

Ensure Node.js is installed:

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

Install Node.js dependencies:
```
npm ci
```

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

Installation: Docker from Source

[!NOTE]
Docker from source requires Docker installed and running on your system.

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```
Ensure Docker is installed:
```
docker --version # Ideally >= v27.x
```
Build the Docker image:
```
docker build -t mongodb-lens .
```

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

Installation Verification

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

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

The server should respond with a list of databases in your MongoDB instance, for example:

{"result":{"contents":[{"uri":"mongodb://databases","text":"Databases (12):\n- admin (180.00 KB)\n- config (108.00 KB)\n- local (40.00 KB)\n- sample_airbnb (51.88 MB)\n- sample_analytics (9.46 MB)\n- sample_geospatial (980.00 KB)\n- sample_guides (40.00 KB)\n- sample_mflix (108.90 MB)\n- sample_restaurants (7.73 MB)\n- sample_supplies (968.00 KB)\n- sample_training (40.85 MB)\n- sample_weatherdata (2.69 MB)"}]},"jsonrpc":"2.0","id":1}

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

Installation: Older MongoDB Versions

To use MongoDB Lens with older MongoDB instances, you need to use a MongoDB Node.js driver version from the 3.x series (e.g. 3.7.4 which is compatible with MongoDB 3.6).

Older MongoDB Versions: Running from Source

Clone the MongoDB Lens repository:

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

Navigate to the cloned repository directory:
```
cd /path/to/mongodb-lens
```

Modify package.json:

"dependencies": {
  ...
-  "mongodb": "^6.15.0",  // Or whatever newer version is listed
+  "mongodb": "^3.7.4",   // Or whatever 3.x version is compatible with your older MongoDB instance
  ...
}

Install Node.js dependencies:
```
npm install
```

Start MongoDB Lens:

node mongodb-lens.js mongodb://older-mongodb-instance

This will use the older driver version compatible with your MongoDB instance.

[!NOTE]
You may also need to revert this commit to add back useNewUrlParser and useUnifiedTopology MongoDB configuration options.

Older MongoDB Versions: Using NPX or Docker

If you prefer to use NPX or Docker, you'll need to use an older version of MongoDB Lens that was published with a compatible driver.

For example, MongoDB Lens 8.3.0 uses MongoDB Node.js driver 3.7.4 (see: package-lock.json).

To run an older version of MongoDB Lens using NPX, specify the version tag:

npx -y mongodb-lens@8.3.0

Similarly for Docker:

docker run --rm -i --network=host furey/mongodb-lens:8.3.0

Configuration

MongoDB Connection String
Config File
Config File Generation
Multiple MongoDB Connections
Environment Variable Overrides
Cross-Platform Environment Variables

Configuration: MongoDB Connection String

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

Example NPX usage:

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

MongoDB connection strings have the following format:

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

Example connection strings:

Local connection:
mongodb://localhost:27017
Connection to mydatabase with credentials from admin database:
mongodb://username:password@hostname:27017/mydatabase?authSource=admin
Connection to mydatabase with various other options:
mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority

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

Configuration: Config File

MongoDB Lens supports extensive customization via JSON configuration file.

[!NOTE]
The config file is optional. MongoDB Lens will run with default settings if no config file is provided.

[!TIP]
You only need to include the settings you want to customize in the config file. MongoDB Lens will use default settings for any omitted values.

[!TIP]
MongoDB Lens supports both .json and .jsonc (JSON with comments) config file formats.

Example configuration file

{
  "mongoUri": "mongodb://localhost:27017",         // Default MongoDB connection string or object of alias-URI pairs
  "connectionOptions": {
    "maxPoolSize": 20,                             // Maximum number of connections in the pool
    "retryWrites": false,                          // Whether to retry write operations
    "connectTimeoutMS": 30000,                     // Connection timeout in milliseconds
    "socketTimeoutMS": 360000,                     // Socket timeout in milliseconds
    "heartbeatFrequencyMS": 10000,                 // How often to ping servers for status
    "serverSelectionTimeoutMS": 30000              // Timeout for server selection
  },
  "defaultDbName": "admin",                        // Default database if not specified in URI
  "connection": {
    "maxRetries": 5,                               // Maximum number of initial connection attempts
    "maxRetryDelayMs": 30000,                      // Maximum delay between retries
    "reconnectionRetries": 10,                     // Maximum reconnection attempts if connection lost
    "initialRetryDelayMs": 1000                    // Initial delay between retries
  },
  "disabled": {
    "tools": [],                                   // Array of tools to disable or true to disable all
    "prompts": [],                                 // Array of prompts to disable or true to disable all
    "resources": []                                // Array of resources to disable or true to disable all
  },
  "enabled": {
    "tools": true,                                 // Array of tools to enable or true to enable all
    "prompts": true,                               // Array of prompts to enable or true to enable all
    "resources": true                              // Array of resources to enable or true to enable all
  },
  "cacheTTL": {
    "stats": 15000,                                // Stats cache lifetime in milliseconds
    "fields": 30000,                               // Fields cache lifetime in milliseconds
    "schemas": 60000,                              // Schema cache lifetime in milliseconds
    "indexes": 120000,                             // Index cache lifetime in milliseconds
    "collections": 30000,                          // Collections list cache lifetime in milliseconds
    "serverStatus": 20000                          // Server status cache lifetime in milliseconds
  },
  "enabledCaches": [                               // List of caches to enable
    "stats",                                       // Statistics cache
    "fields",                                      // Collection fields cache
    "schemas",                                     // Collection schemas cache
    "indexes",                                     // Collection indexes cache
    "collections",                                 // Database collections cache
    "serverStatus"                                 // MongoDB server status cache
  ],
  "memory": {
    "enableGC": true,                              // Whether to enable garbage collection
    "warningThresholdMB": 1500,                    // Memory threshold for warnings
    "criticalThresholdMB": 2000                    // Memory threshold for cache clearing
  },
  "logLevel": "info",                              // Log level (info or verbose)
  "disableDestructiveOperationTokens": false,      // Whether to skip confirmation for destructive ops
  "watchdogIntervalMs": 30000,                     // Interval for connection monitoring
  "defaults": {
    "slowMs": 100,                                 // Threshold for slow query detection
    "queryLimit": 10,                              // Default limit for query results
    "allowDiskUse": true,                          // Allow operations to use disk for large datasets
    "schemaSampleSize": 100,                       // Sample size for schema inference
    "aggregationBatchSize": 50                     // Batch size for aggregation operations
  },
  "security": {
    "tokenLength": 4,                              // Length of confirmation tokens
    "tokenExpirationMinutes": 5,                   // Expiration time for tokens
    "strictDatabaseNameValidation": true           // Enforce strict database name validation
  },
  "tools": {
    "transaction": {
      "readConcern": "snapshot",                   // Read concern level for transactions
      "writeConcern": {
        "w": "majority"                            // Write concern for transactions
      }
    },
    "bulkOperations": {
      "ordered": true                              // Whether bulk operations execute in order
    },
    "export": {
      "defaultLimit": -1,                          // Default limit for exports (-1 = no limit)
      "defaultFormat": "json"                      // Default export format (json or csv)
    },
    "watchChanges": {
      "maxDurationSeconds": 60,                    // Maximum duration for change streams
      "defaultDurationSeconds": 10                 // Default duration for change streams
    },
    "queryAnalysis": {
      "defaultDurationSeconds": 10                 // Default duration for query analysis
    }
  }
}

By default, MongoDB Lens looks for the config file at:

~/.mongodb-lens.jsonc first, then falls back to
~/.mongodb-lens.json if the former doesn't exist

To customize the config file path, set the environment variable CONFIG_PATH to the desired file path.

Example NPX usage:

CONFIG_PATH='/path/to/config.json' npx -y mongodb-lens@latest

Example Docker Hub usage:

docker run --rm -i --network=host --pull=always -v /path/to/config.json:/root/.mongodb-lens.json furey/mongodb-lens

Configuration: Config File Generation

You can generate a configuration file automatically using the config:create script:

# NPX Usage (recommended)
npx -y mongodb-lens@latest config:create

# Node.js Usage
npm run config:create

# Force overwrite existing files
npx -y mongodb-lens@latest config:create -- --force
npm run config:create -- --force

This script extracts the example configuration file above and saves it to: ~/.mongodb-lens.jsonc

Config File Generation: Custom Path

You can specify a custom output location using the CONFIG_PATH environment variable.

If CONFIG_PATH has no file extension, it's treated as a directory and .mongodb-lens.jsonc is appended
If CONFIG_PATH ends with .json (not .jsonc) comments are removed from the generated file

Example NPX usage:

# With custom path
CONFIG_PATH=/path/to/config.jsonc npx -y mongodb-lens@latest config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory npx -y mongodb-lens@latest config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json npx -y mongodb-lens@latest config:create

Example Node.js usage:

# With custom path
CONFIG_PATH=/path/to/config.jsonc node mongodb-lens.js config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory node mongodb-lens.js config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json node mongodb-lens.js config:create

Configuration: Multiple MongoDB Connections

MongoDB Lens supports multiple MongoDB URIs with aliases in your config file, allowing you to easily switch between different MongoDB instances using simple names.

To configure multiple connections, set the mongoUri config setting to an object with alias-URI pairs:

{
  "mongoUri": {
    "main": "mongodb://localhost:27017",
    "backup": "mongodb://localhost:27018",
    "atlas": "mongodb+srv://username:password@cluster.mongodb.net/mydb"
  }
}

With this configuration:

The first URI in the list (e.g. main) becomes the default connection at startup
You can switch connections using natural language: "Connect to backup" or "Connect to atlas"
The original syntax still works: "Connect to mongodb://localhost:27018"
The list-connections tool shows all available connection aliases

[!NOTE]
When using the command-line argument to specify a connection, you can use either a full MongoDB URI or an alias defined in your configuration file.

[!TIP]
To add connection aliases at runtime, use the add-connection-alias tool.

Configuration: Environment Variable Overrides

MongoDB Lens supports environment variable overrides for configuration settings.

Environment variables take precedence over config file settings.

Config environment variables follow the naming pattern:

CONFIG_[SETTING PATH, SNAKE CASED, UPPERCASED]

Example overrides:

Config Setting	Environment Variable Override
`mongoUri`	`CONFIG_MONGO_URI`
`logLevel`	`CONFIG_LOG_LEVEL`
`defaultDbName`	`CONFIG_DEFAULT_DB_NAME`
`defaults.queryLimit`	`CONFIG_DEFAULTS_QUERY_LIMIT`
`tools.export.defaultFormat`	`CONFIG_TOOLS_EXPORT_DEFAULT_FORMAT`
`connectionOptions.maxPoolSize`	`CONFIG_CONNECTION_OPTIONS_MAX_POOL_SIZE`
`connection.reconnectionRetries`	`CONFIG_CONNECTION_RECONNECTION_RETRIES`

For environment variable values:

For boolean settings, use string values 'true' or 'false'.
For numeric settings, use string representations.
For nested objects or arrays, use JSON strings.

Example NPX usage:

CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

Example Docker Hub usage:

docker run --rm -i --network=host --pull=always -e CONFIG_DEFAULTS_QUERY_LIMIT='25' furey/mongodb-lens

Configuration: Cross-Platform Environment Variables

For consistent environment variable usage across Windows, macOS, and Linux, consider using cross-env:

Install cross-env globally:

# Using NPM
npm install -g cross-env

# Using Volta (see: https://volta.sh)
volta install cross-env

Prefix any NPX or Node.js environment variables in this document's examples:

# Example NPX usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

# Example Node.js usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' node mongodb-lens.js

Client Setup

Claude Desktop
MCP Inspector
Other MCP Clients

Client Setup: Claude Desktop

To use MongoDB Lens with Claude Desktop:

Install Claude Desktop
Open claude_desktop_config.json (create if it doesn't exist):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the MongoDB Lens server configuration as per configuration options
Restart Claude Desktop
Start a conversation with Claude about your MongoDB data

Claude Desktop Configuration Options

Option 1: NPX (Recommended)
Option 2: Docker Hub Image
Option 3: Local Node.js Installation
Option 4: Local Docker Image

For each option:

Replace mongodb://your-connection-string with your MongoDB connection string or omit it to use the default mongodb://localhost:27017.
To use a custom config file, set CONFIG_PATH environment variable.

To include environment variables:

For NPX or Node.js add "env": {} with key-value pairs, for example:

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

For Docker add -e flags, for example:

"command": "docker",
"args": [
  "run", "--rm", "-i",
  "--network=host",
  "--pull=always",
  "-e", "CONFIG_LOG_LEVEL=verbose",
  "furey/mongodb-lens",
  "mongodb://your-connection-string"
]

Option 1: NPX (Recommended)

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

Option 2: Docker Hub Image

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "--pull=always",
        "furey/mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Option 3: Local Node.js Installation

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/node",
      "args": [
        "/path/to/mongodb-lens.js",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Option 4: Local Docker Image

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Client Setup: MCP Inspector

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

[!NOTE]
MCP Inspector starts a proxy server on port 3000 and web client on port 5173.

Example NPX usage:

Run MCP Inspector:

# Using default connection string mongodb://localhost:27017
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

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

# Using custom ports
SERVER_PORT=1234 CLIENT_PORT=5678 npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

Open MCP Inspector: http://localhost:5173

MCP Inspector should support 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 should be usable with any MCP-compatible client.

For more, see: MCP Documentation: Example Clients

Data Protection

To protect your data while using MongoDB Lens, consider the following:

Read-Only User Accounts
Working with Database Backups
Data Flow Considerations
Confirmation for Destructive Operations
Disabling Destructive Operations

Data Protection: Read-Only User Accounts

To set this up, create a user with the read role scoped to the database(s) you're targeting. In MongoDB shell, you'd run something like:

use admin

db.createUser({
  user: 'readonly',
  pwd: 'eXaMpLePaSsWoRd',
  roles: [{ role: 'read', db: 'mydatabase' }]
})

Then, apply those credentials to your MongoDB connection string:

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

Using read-only credentials is a simple yet effective way to enforce security boundaries, especially when you're poking around schemas or running ad-hoc queries.

Data Protection: Working with Database Backups

When working with MongoDB Lens, consider connecting to a backup copy of your data hosted on a separate MongoDB instance.

This approach gives you a sandbox to test complex or destructive operations against without risking accidental corruption of your live data.

Data Protection: Data Flow Considerations

How Your Data Flows Through the System
Protecting Sensitive Data with Projection
Connection Aliases and Passwords
Local Setup for Maximum Safety

Data Flow Considerations: How Your Data Flows Through the System

When you send a MongoDB related query through your MCP client, here’s what happens:

[!NOTE]
While this example uses a local MongoDB instance, the same principles apply to remote MongoDB instances.

sequenceDiagram
    actor User
    box Local Machine #d4f1f9
        participant Client as MCP Client
        participant Lens as MongoDB Lens
        participant MongoDB as MongoDB Instance
    end
    box Remote Server #ffe6cc
        participant LLM as Remote LLM Provider
    end

    User->>Client: 1. Submit request<br>"Show me all users older than 30"
    Client->>LLM: 2. User request + available tools
    Note over LLM: Interprets request<br>Chooses appropriate tool
    LLM->>Client: 3. Tool selection (find-documents)
    Client->>Lens: 4. Tool run with parameters
    Lens->>MongoDB: 5. Database query
    MongoDB-->>Lens: 6. Database results
    Lens-->>Client: 7. Tool results (formatted data)
    Client->>LLM: 8. Tool results
    Note over LLM: Processes results<br>Formats response
    LLM-->>Client: 9. Processed response
    Client-->>User: 10. Final answer

You submit a request
^{➥ e.g. "Show me all users older than 30"}
Your client sends the request to the remote LLM
^{➥ The LLM provider receives your exact words along with a list of available MCP tools and their parameters.}
The remote LLM interprets your request
^{➥ It determines your intent and instructs the client to use a specific MCP tool with appropriate parameters.}
The client asks MongoDB Lens to run the tool
^{➥ This occurs locally on your machine via stdio.}
MongoDB Lens queries your MongoDB database
MongoDB Lens retrieves your MongoDB query results
MongoDB Lens sends the data back to the client
^{➥ The client receives results formatted by MongoDB Lens.}
The client forwards the data to the remote LLM
^{➥ The LLM provider sees the exact data returned by MongoDB Lens.}
The remote LLM processes the data
^{➥ It may summarize or format the results further.}
The remote LLM sends the final response to the client
^{➥ The client displays the answer to you.}

Data Flow Considerations: Protecting Sensitive Data with Projection

Example projection usage:

"Show me all users older than 30, but use projection to hide their passwords."
^{➥ Uses find-documents tool with projection}

Data Flow Considerations: Connection Aliases and Passwords

Data Flow Considerations: Local Setup for Maximum Safety

Data Protection: Confirmation for Destructive Operations

MongoDB Lens implements a token-based confirmation system for potentially destructive operations, requiring a two-step process to execute tools that may otherwise result in unchecked data loss:

First tool invocation: Returns a 4-digit confirmation token that expires after 5 minutes
Second tool invocation: Executes the operation if provided with the valid token

For an example of the confirmation process, see: Working with Confirmation Protection

Tools that require confirmation include:

drop-user: Remove a database user
drop-index: Remove an index (potential performance impact)
drop-database: Permanently delete a database
drop-collection: Delete a collection and all its documents
delete-document: Delete one or multiple documents
bulk-operations: When including delete operations
rename-collection: When the target collection exists and will be dropped

[!NOTE]
If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to bypass confirmation and perform destructive operations immediately.

Bypassing Confirmation for Destructive Operations

You might want to bypass the token confirmation system.

Set the environment variable CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS to true to execute destructive operations immediately without confirmation:

# Using NPX
CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS=true npx -y mongodb-lens@latest

# Using Docker
docker run --rm -i --network=host --pull=always -e CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS='true' furey/mongodb-lens

[!WARNING]
Disabling confirmation tokens removes an important safety mechanism. It's strongly recommended to only use this option in controlled environments where data loss is acceptable, such as development or testing. Disable at your own risk.

Data Protection: Disabling Destructive Operations

Disabling Tools
High-Risk Tools
Medium-Risk Tools
Read-Only Configuration
Selective Component Enabling

Disabling Tools

MongoDB Lens includes several tools that can modify or delete data. To disable specific tools, add them to the disabled.tools array in your configuration file:

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

[!NOTE]
Resources and prompts can also be disabled via disabled.resources and disabled.prompts settings.

High-Risk Tools

These tools can cause immediate data loss and should be considered for disabling in sensitive environments:

drop-user: Removes database users and their access permissions
drop-index: Removes indexes (can impact query performance)
drop-database: Permanently deletes entire databases
drop-collection: Permanently deletes collections and all their documents
delete-document: Removes documents matching specified criteria
bulk-operations: Can perform batch deletions when configured to do so
rename-collection: Can overwrite existing collections when using the drop target option

Medium-Risk Tools

These tools can modify data but typically don't cause immediate data loss:

create-user: Creates users with permissions that could enable further changes
transaction: Executes multiple operations in a transaction (potential for complex changes)
update-document: Updates documents which could overwrite existing data

Read-Only Configuration

For a complete read-only configuration, disable all potentially destructive tools:

{
  "disabled": {
    "tools": [
      "drop-user",
      "drop-index",
      "create-user",
      "transaction",
      "create-index",
      "drop-database",
      "drop-collection",
      "insert-document",
      "update-document",
      "delete-document",
      "bulk-operations",
      "create-database",
      "gridfs-operation",
      "create-collection",
      "rename-collection",
      "create-timeseries"
    ]
  }
}

This configuration allows MongoDB Lens to query and analyze data while preventing any modifications, providing multiple layers of protection against accidental data loss.

Selective Component Enabling

In addition to disabling components, specify exactly which components should be enabled (implicitly disabling all others) using the enabled settings in your configuration file:

{
  "enabled": {
    "tools": [
      "use-database",
      "find-documents",
      "count-documents",
      "aggregate-data"
    ]
  },
  "disabled": {
    "resources": true,
    "prompts": true
  }
}

[!IMPORTANT]
If a component appears in both enabled and disabled lists, the enabled setting takes precedence.

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:

Start Sample Data Container
Import Sample Data
Connect MongoDB Lens
Example Queries
Working With Confirmation Protection

Tutorial: 1. Start Sample Data Container

[!NOTE]
This tutorial assumes you have Docker installed and running on your system.

[!IMPORTANT]
If Docker is already running a container on port 27017, stop it before proceeding.

Initialise the sample data container:

docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6

Verify the container is running without issue:
```
docker ps | grep mongodb-sampledata
```

Tutorial: 2. Import Sample Data

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

Download the sample datasets:

curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive

Copy the sample datasets into your sample data container:
```
docker cp sampledata.archive mongodb-sampledata:/tmp/
```

Import the sample datasets into MongoDB:

docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive

This will import several databases:

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: 3. Connect MongoDB Lens

Install MongoDB Lens as per the Quick Start instructions.

Set your MCP Client to connect to MongoDB Lens via: mongodb://localhost:27017

[!TIP]
Omitting the connection string from your MCP Client configuration will default the connection string to mongodb://localhost:27017.

Example Claude Desktop configuration:

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

Tutorial: 4. Example Queries

With your MCP Client running and connected to MongoDB Lens, try the following example queries:

Example Queries: Basic Database Operations
Example Queries: Collection Management
Example Queries: User Management
Example Queries: Querying Data
Example Queries: Schema Analysis
Example Queries: Data Modification
Example Queries: Performance & Index Management
Example Queries: Geospatial & Special Operations
Example Queries: Export, Administrative & Other Features
Example Queries: Connection Management

Example Queries: Basic Database Operations

"List all databases"
^{➥ Uses list-databases tool}
"What db am I currently using?"
^{➥ Uses current-database tool}
"Switch to the sample_mflix database"
^{➥ Uses use-database tool}
"Create a new db called test_db"
^{➥ Uses create-database tool}
"Create another db called analytics_db and switch to it"
^{➥ Uses create-database tool with switch=true}
"Drop test_db"
^{➥ Uses drop-database tool (with confirmation)}

Example Queries: Collection Management

"What collections are in the current database?"
^{➥ Uses list-collections tool}
"Create user_logs collection"
^{➥ Uses create-collection tool}
"Rename user_logs to system_logs"
^{➥ Uses rename-collection tool}
"Drop system_logs"
^{➥ Uses drop-collection tool (with confirmation)}
"Check the data consistency in the movies collection"
^{➥ Uses validate-collection tool}

Example Queries: User Management

"Create a read-only user for analytics"
^{➥ Uses create-user tool}
"Drop the inactive_user account"
^{➥ Uses drop-user tool (with confirmation)}

Example Queries: Querying Data

"Count all docs in the movies collection"
^{➥ Uses count-documents tool}
"Find the top 5 movies with the highest IMDB rating"
^{➥ Uses find-documents tool}
"Show me aggregate data for movies grouped by decade"
^{➥ Uses aggregate-data tool}
"List all unique countries where movies were produced"
^{➥ Uses distinct-values tool}
"Search for movies containing godfather in their title"
^{➥ Uses text-search tool}
"Find German users with last name müller using proper collation"
^{➥ Uses collation-query tool}

Example Queries: Schema Analysis

"What's the schema structure of the movies collection?"
^{➥ Uses analyze-schema tool}
"Compare users and comments schemas"
^{➥ Uses compare-schemas tool}
"Generate a schema validator for the movies collection"
^{➥ Uses generate-schema-validator tool}
"Analyze common query patterns for the movies collection"
^{➥ Uses analyze-query-patterns tool}

Example Queries: Data Modification

"Insert new movie document: <your field data>"
^{➥ Uses insert-document tool}
"Update all movies from 1994 to add a 'classic' flag"
^{➥ Uses update-document tool}
"Delete all movies with zero ratings"
^{➥ Uses delete-document tool (with confirmation)}
"Run these bulk operations on the movies collection: <your JSON data>"
^{➥ Uses bulk-operations tool}

[!TIP]
For specialized MongoDB operations (like array operations, bitwise operations, or other complex updates), use MongoDB's native operators via the update-document tool's update and options parameters.

Example Queries: Performance & Index Management

"Create an index on the title field in the movies collection"
^{➥ Uses create-index tool}
"Drop the ratings_idx index"
^{➥ Uses drop-index tool (with confirmation)}
"Explain the execution plan for finding movies from 1995"
^{➥ Uses explain-query tool}
"Get statistics for the current db"
^{➥ Uses get-stats tool with target=database}
"Show collection stats for the movies collection"
^{➥ Uses get-stats tool with target=collection}

Example Queries: Geospatial & Special Operations

"Switch to sample_geospatial db, then find all shipwrecks within 10km of coordinates [-80.12, 26.46]"
^{➥ Uses geo-query tool}
"Switch to sample_analytics db, then execute a transaction to move funds between accounts: <account ids>"
^{➥ Uses transaction tool}
"Create a time series collection for sensor readings"
^{➥ Uses create-timeseries tool}
"Watch for changes in the users collection for 30 seconds"
^{➥ Uses watch-changes tool}
"List all files in the images GridFS bucket"
^{➥ Uses gridfs-operation tool with operation=list}

Example Queries: Export, Administrative & Other Features

"Switch to sample_mflix db, then export the top 20 movies based on 'tomatoes.critic.rating' as a CSV with title, year and rating fields (output in a single code block)"
^{➥ Uses export-data tool}
"Switch to sample_analytics db, then check its sharding status"
^{➥ Uses shard-status tool}
"Clear the collections cache"
^{➥ Uses clear-cache tool with target=collections}
"Clear all caches"
^{➥ Uses clear-cache tool}
"Switch to sample_weatherdata db then generate an interactive report on its current state"
^{➥ Uses numerous tools}

Example Queries: Connection Management

"Connect to mongodb://localhost:27018"
^{➥ Uses connect-mongodb tool}
"Connect to mongodb+srv://username:password@cluster.mongodb.net/mydb"
^{➥ Uses connect-mongodb tool}
"Connect back to the original mongodb instance"
^{➥ Uses connect-original tool}
"Connect to replica set without validating the connection: <replica set details>"
^{➥ Uses connect-mongodb tool with validateConnection=false}
"Add connection alias 'prod' for mongodb://username:password@prod-server:27017/mydb"
^{➥ Uses add-connection-alias tool}

Tutorial: 5. Working With Confirmation Protection

MongoDB Lens includes a safety mechanism for potentially destructive operations. Here's how it works in practice:

Request to drop a collection:

"Drop the collection named test_collection"

MongoDB Lens responds with a warning and confirmation token:

⚠️ DESTRUCTIVE OPERATION WARNING ⚠️

You've requested to drop the collection 'test_collection'.

This operation is irreversible and will permanently delete all data in this collection.

To confirm, you must type the 4-digit confirmation code EXACTLY as shown below:

Confirmation code: 9876

This code will expire in 5 minutes for security purposes.

Confirm the operation by submitting the confirmation token:
```
"9876"
```

MongoDB Lens executes the operation:

Collection 'test_collection' has been permanently deleted.

This two-step process prevents accidental data loss by requiring explicit confirmation.

[!NOTE]
If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to bypass confirmation and perform destructive operations immediately.

Test Suite

MongoDB Lens includes a test suite to verify functionality across tools, resources, and prompts.

Running Tests
Command Line Options
Examples

Test Suite: Running Tests

The test suite requires a CONFIG_MONGO_URI environment variable which can be set to:

a MongoDB connection string (e.g. mongodb://localhost:27017)
mongodb-memory-server (for in-memory testing)

# Run Tests with MongoDB Connection String
CONFIG_MONGO_URI=mongodb://localhost:27017 node mongodb-lens.test.js

# Run Tests with In-Memory MongoDB (requires mongodb-memory-server)
CONFIG_MONGO_URI=mongodb-memory-server node mongodb-lens.test.js

For convenience, the following scripts are available for running tests:

npm test                        # Fails if no CONFIG_MONGO_URI provided
npm run test:localhost          # Uses mongodb://localhost:27017
npm run test:localhost:verbose  # Runs with DEBUG=true for verbose output
npm run test:in-memory          # Uses mongodb-memory-server
npm run test:in-memory:verbose  # Runs with DEBUG=true for verbose output

[!NOTE]
The test suite creates temporary databases and collections that are cleaned up after test completion.

Test Suite: Command Line Options

Option	Description
`--list`	List all available tests without running them
`--test=<n>`	Run specific test(s) by name (comma-separated)
`--group=<n>`	Run all tests in specific group(s) (comma-separated)
`--pattern=<glob>`	Run tests matching pattern(s) (comma-separated)

Test Suite: Examples

# List All Available Tests
npm test -- --list

# Run Only Connection-Related Tests (:27017)
npm run test:localhost -- --group=Connection\ Tools

# Test Specific Database Operations (In-Memory)
npm run test:in-memory -- --test=create-database\ Tool,drop-database\ Tool

# Test All Document-Related Tools (:27017)
npm run test:localhost -- --pattern=document

# Run Resource Tests Only (In-Memory)
npm run test:in-memory -- --group=Resources

# Run Specific Tests Only (In-Memory)
npm run test:in-memory -- --test=aggregate-data\ Tool,find-documents\ Tool

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—please use at your own risk.

Support

If you've found MongoDB Lens helpful consider supporting my work through:

Buy Me a Coffee | GitHub Sponsorship

Contributions help me continue developing and improving this tool, allowing me to dedicate more time to add new features and ensuring it remains a valuable resource for the community.

mongodb-lens

README Documentation

MongoDB Lens

Contents

Quick Start

Features

Tools

Resources

Prompts

Other Features

Other Features: Overview

Other Features: New Database Metadata

Installation

Installation: NPX

Installation: Docker Hub

Installation: Node.js from Source

Installation: Docker from Source

Installation Verification

Installation: Older MongoDB Versions

Older MongoDB Versions: Running from Source

Older MongoDB Versions: Using NPX or Docker

Configuration

Configuration: MongoDB Connection String

Configuration: Config File

Configuration: Config File Generation

Config File Generation: Custom Path

Configuration: Multiple MongoDB Connections

Configuration: Environment Variable Overrides

Configuration: Cross-Platform Environment Variables

Client Setup

Client Setup: Claude Desktop

Claude Desktop Configuration Options

Option 1: NPX (Recommended)

Option 2: Docker Hub Image

Option 3: Local Node.js Installation

Option 4: Local Docker Image

Client Setup: MCP Inspector

Client Setup: Other MCP Clients

Data Protection

Data Protection: Read-Only User Accounts

Data Protection: Working with Database Backups

Data Protection: Data Flow Considerations

Data Flow Considerations: How Your Data Flows Through the System

Data Flow Considerations: Protecting Sensitive Data with Projection

Data Flow Considerations: Connection Aliases and Passwords

Data Flow Considerations: Local Setup for Maximum Safety

Data Protection: Confirmation for Destructive Operations

Bypassing Confirmation for Destructive Operations

Data Protection: Disabling Destructive Operations

Disabling Tools

High-Risk Tools

Medium-Risk Tools

Read-Only Configuration

Selective Component Enabling

Tutorial

Tutorial: 1. Start Sample Data Container

Tutorial: 2. Import Sample Data

Tutorial: 3. Connect MongoDB Lens

Tutorial: 4. Example Queries

Example Queries: Basic Database Operations

Example Queries: Collection Management

Example Queries: User Management

Example Queries: Querying Data

Example Queries: Schema Analysis

Example Queries: Data Modification

Example Queries: Performance & Index Management

Example Queries: Geospatial & Special Operations

Example Queries: Export, Administrative & Other Features

Example Queries: Connection Management

Tutorial: 5. Working With Confirmation Protection

Test Suite

Test Suite: Running Tests

Test Suite: Command Line Options

Test Suite: Examples

Disclaimer

Support

Quick Install

Quick Actions

Key Features

mongodb-lens