Example metadata document

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

\n\nOnce you've added your own collections to your new database, you can safely remove the `metadata` collection via the `drop-collection` tool:\n\n- _\"Drop the new database's metadata collection\"_
\n ^{➥ Uses `drop-collection` tool (with confirmation)}\n\n## Installation\n\nMongoDB Lens can be installed and run in several ways:\n\n- [NPX](#installation-npx) (Easiest)\n- [Docker Hub](#installation-docker-hub)\n- [Node.js from Source](#installation-nodejs-from-source)\n- [Docker from Source](#installation-docker-from-source)\n- [Installation Verification](#installation-verification)\n\n### Installation: NPX\n\n> [!NOTE]
\n> NPX requires [Node.js](https://nodejs.org/en/download) installed and running on your system (suggestion: use [Volta](https://volta.sh)).\n\nThe easiest way to run MongoDB Lens is using `npx`.\n\nFirst, ensure Node.js is installed:\n\n```console\nnode --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible\n```\n\nThen, run MongoDB Lens via NPX:\n\n```console\n# Using default connection string mongodb://localhost:27017\nnpx -y mongodb-lens\n\n# Using custom connection string\nnpx -y mongodb-lens mongodb://your-connection-string\n\n# Using \"@latest\" to keep the package up-to-date\nnpx -y mongodb-lens@latest\n```\n\n> [!TIP]
\n> 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).\n\n### Installation: Docker Hub\n\n> [!NOTE]
\n> Docker Hub requires [Docker](https://docs.docker.com/get-started/get-docker) installed and running on your system.\n\nFirst, ensure Docker is installed:\n\n```console\ndocker --version # Ideally >= v27.x\n```\n\nThen, run MongoDB Lens via Docker Hub:\n\n```console\n# Using default connection string mongodb://localhost:27017\ndocker run --rm -i --network=host furey/mongodb-lens\n\n# Using custom connection string\ndocker run --rm -i --network=host furey/mongodb-lens mongodb://your-connection-string\n\n# Using \"--pull\" to keep the Docker image up-to-date\ndocker run --rm -i --network=host --pull=always furey/mongodb-lens\n```\n\n### Installation: Node.js from Source\n\n> [!NOTE]
\n> Node.js from source requires [Node.js](https://nodejs.org/en/download) installed and running on your system (suggestion: use [Volta](https://volta.sh)).\n\n1. Clone the MongoDB Lens repository:
\n ```console\n git clone https://github.com/furey/mongodb-lens.git\n ```\n1. Navigate to the cloned repository directory:
\n ```console\n cd /path/to/mongodb-lens\n ```\n1. Ensure Node.js is installed:
\n ```console\n node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible\n ```\n1. Install Node.js dependencies:
\n ```console\n npm ci\n ```\n1. Start the server:
\n ```console\n # Using default connection string mongodb://localhost:27017\n node mongodb-lens.js\n\n # Using custom connection string\n node mongodb-lens.js mongodb://your-connection-string\n ```\n\n### Installation: Docker from Source\n\n> [!NOTE]
\n> Docker from source requires [Docker](https://docs.docker.com/get-started/get-docker) installed and running on your system.\n\n1. Clone the MongoDB Lens repository:
\n ```console\n git clone https://github.com/furey/mongodb-lens.git\n ```\n1. Navigate to the cloned repository directory:
\n ```console\n cd /path/to/mongodb-lens\n ```\n1. Ensure Docker is installed:
\n ```console\n docker --version # Ideally >= v27.x\n ```\n1. Build the Docker image:
\n ```console\n docker build -t mongodb-lens .\n ```\n1. Run the container:
\n ```console\n # Using default connection string mongodb://localhost:27017\n docker run --rm -i --network=host mongodb-lens\n\n # Using custom connection string\n docker run --rm -i --network=host mongodb-lens mongodb://your-connection-string\n ```\n\n### Installation Verification\n\nTo verify the installation, paste and run the following jsonrpc message into the server's stdio:\n\n```json\n{\"method\":\"resources/read\",\"params\":{\"uri\":\"mongodb://databases\"},\"jsonrpc\":\"2.0\",\"id\":1}\n```\n\nThe server should respond with a list of databases in your MongoDB instance, for example:\n\n```json\n{\"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}\n```\n\nMongoDB Lens is now installed and ready to accept MCP requests.\n\n## Configuration\n\n- [MongoDB Connection String](#configuration-mongodb-connection-string)\n- [Config File](#configuration-config-file)\n- [Config File Generation](#configuration-config-file-generation)\n- [Multiple MongoDB Connections](#configuration-multiple-mongodb-connections)\n- [Environment Variable Overrides](#configuration-environment-variable-overrides)\n- [Cross-Platform Environment Variables](#configuration-cross-platform-environment-variables)\n\n### Configuration: MongoDB Connection String\n\nThe server accepts a MongoDB connection string as its only argument.\n\nExample NPX usage:\n\n```console\nnpx -y mongodb-lens@latest mongodb://your-connection-string\n```\n\nMongoDB connection strings have the following format:\n\n```txt\nmongodb://[username:password@]host[:port][/database][?options]\n```\n\nExample connection strings:\n\n- Local connection:
\n `mongodb://localhost:27017`\n- Connection to `mydatabase` with credentials from `admin` database:
\n `mongodb://username:password@hostname:27017/mydatabase?authSource=admin`\n- Connection to `mydatabase` with various other options:
\n `mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority`\n\nIf no connection string is provided, the server will attempt to connect via local connection.\n\n### Configuration: Config File\n\nMongoDB Lens supports extensive customization via JSON configuration file.\n\n> [!NOTE]
\n> The config file is optional. MongoDB Lens will run with default settings if no config file is provided.\n\n> [!TIP]
\n> 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.\n\n> [!TIP]
\n> MongoDB Lens supports both `.json` and `.jsonc` (JSON with comments) config file formats.\n\n

Example configuration file

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

\n\nBy default, MongoDB Lens looks for the config file at:\n\n- `~/.mongodb-lens.jsonc` first, then falls back to\n- `~/.mongodb-lens.json` if the former doesn't exist\n\nTo customize the config file path, set the environment variable `CONFIG_PATH` to the desired file path.\n\nExample NPX usage:\n\n```console\nCONFIG_PATH='/path/to/config.json' npx -y mongodb-lens@latest\n```\n\nExample Docker Hub usage:\n\n```console\ndocker run --rm -i --network=host --pull=always -v /path/to/config.json:/root/.mongodb-lens.json furey/mongodb-lens\n```\n\n### Configuration: Config File Generation\n\nYou can generate a configuration file automatically using the `config:create` script:\n\n```console\n# Create config file\nnpm run config:create\n\n# Create config file (force overwrite existing)\nnpm run config:create -- --force\n```\n\nThis script extracts the [example configuration file](#configuration-config-file) above and saves it to: `~/.mongodb-lens.jsonc`\n\n#### Config File Generation: Custom Path\n\nYou can specify a custom configuration file output location using the `CONFIG_PATH` environment variable:\n\n```console\n# Save to a specific file path\nCONFIG_PATH=/path/to/config.jsonc npm run config:create\n\n# Save to a specific directory (will append .mongodb-lens.jsonc to the path)\nCONFIG_PATH=/path/to/directory npm run config:create\n\n# Save as JSON without comments\nCONFIG_PATH=/path/to/config.json npm run config:create\n```\n\nThe script handles paths intelligently:\n\n- If `CONFIG_PATH` has no file extension, it's treated as a directory and `.mongodb-lens.jsonc` is appended\n- If `CONFIG_PATH` ends with `.json` (not `.jsonc`), comments are automatically stripped from the output\n\n### Configuration: Multiple MongoDB Connections\n\nMongoDB Lens supports multiple MongoDB URIs with aliases in your [config file](#configuration-config-file), allowing you to easily switch between different MongoDB instances using simple names.\n\nTo configure multiple connections, set the `mongoUri` config setting to an object with alias-URI pairs:\n\n```json\n{\n \"mongoUri\": {\n \"main\": \"mongodb://localhost:27017\",\n \"backup\": \"mongodb://localhost:27018\",\n \"atlas\": \"mongodb+srv://username:password@cluster.mongodb.net/mydb\"\n }\n}\n```\n\nWith this configuration:\n\n- The first URI in the list (e.g. `main`) becomes the default connection at startup\n- You can switch connections using natural language: `\"Connect to backup\"` or `\"Connect to atlas\"`\n- The original syntax still works: `\"Connect to mongodb://localhost:27018\"`\n- The `list-connections` tool shows all available connection aliases\n\n> [!NOTE]
\n> 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.\n\n### Configuration: Environment Variable Overrides\n\nMongoDB Lens supports environment variable overrides for configuration settings.\n\nEnvironment variables take precedence over [config file](#configuration-config-file) settings.\n\nConfig environment variables follow the naming pattern:\n\n```txt\nCONFIG_[SETTING PATH, SNAKE CASED, UPPERCASED]\n```\n\nExample overrides:\n\n| Config Setting | Environment Variable Override |\n| -------------------------------- | ----------------------------------------- |\n| `mongoUri` | `CONFIG_MONGO_URI` |\n| `logLevel` | `CONFIG_LOG_LEVEL` |\n| `defaultDbName` | `CONFIG_DEFAULT_DB_NAME` |\n| `connectionOptions.maxPoolSize` | `CONFIG_CONNECTION_OPTIONS_MAX_POOL_SIZE` |\n| `connection.reconnectionRetries` | `CONFIG_CONNECTION_RECONNECTION_RETRIES` |\n| `defaults.queryLimit` | `CONFIG_DEFAULTS_QUERY_LIMIT` |\n| `tools.export.defaultFormat` | `CONFIG_TOOLS_EXPORT_DEFAULT_FORMAT` |\n\nFor environment variable values:\n\n- For boolean settings, use string values `'true'` or `'false'`.\n- For numeric settings, use string representations.\n- For nested objects or arrays, use JSON strings.\n\nExample NPX usage:\n\n```console\nCONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest\n```\n\nExample Docker Hub usage:\n\n```console\ndocker run --rm -i --network=host --pull=always -e CONFIG_DEFAULTS_QUERY_LIMIT='25' furey/mongodb-lens\n```\n\n### Configuration: Cross-Platform Environment Variables\n\nFor consistent environment variable usage across Windows, macOS, and Linux, consider using `cross-env`:\n\n1. Install cross-env globally:
\n ```console\n # Using NPM\n npm install -g cross-env\n\n # Using Volta (see: https://volta.sh)\n volta install cross-env\n ```\n1. Prefix any NPX or Node.js environment variables in this document's examples:
\n ```console\n # Example NPX usage with cross-env\n cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest\n\n # Example Node.js usage with cross-env\n cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' node mongodb-lens.js\n ```\n\n## Client Setup\n\n- [Claude Desktop](#client-setup-claude-desktop)\n- [MCP Inspector](#client-setup-mcp-inspector)\n- [Other MCP Clients](#client-setup-other-mcp-clients)\n\n### Client Setup: Claude Desktop\n\nTo use MongoDB Lens with Claude Desktop:\n\n1. Install [Claude Desktop](https://claude.ai/download)\n1. Open `claude_desktop_config.json` (create if it doesn't exist):\n - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n1. Add the MongoDB Lens server configuration as per [configuration options](#claude-desktop-configuration-options)\n1. Restart Claude Desktop\n1. Start a conversation with Claude about your MongoDB data\n\n#### Claude Desktop Configuration Options\n\n- [Option 1: NPX (Recommended)](#option-1-npx-recommended)\n- [Option 2: Docker Hub Image](#option-2-docker-hub-image)\n- [Option 3: Local Node.js Installation](#option-3-local-nodejs-installation)\n- [Option 4: Local Docker Image](#option-4-local-docker-image)\n\nFor each option:\n\n- Replace `mongodb://your-connection-string` with your MongoDB connection string or omit it to use the default `mongodb://localhost:27017`.\n- To use a custom config file, set [`CONFIG_PATH`](#configuration-config-file) environment variable.\n- To include environment variables:\n - For NPX or Node.js add `\"env\": {}` with key-value pairs, for example:
\n ```json\n \"command\": \"/path/to/npx\",\n \"args\": [\n \"-y\",\n \"mongodb-lens@latest\",\n \"mongodb://your-connection-string\"\n ],\n \"env\": {\n \"CONFIG_LOG_LEVEL\": \"verbose\"\n }\n ```\n - For Docker add `-e` flags, for example:
\n ```json\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\",\n \"--network=host\",\n \"--pull=always\",\n \"-e\", \"CONFIG_LOG_LEVEL='verbose'\",\n \"furey/mongodb-lens\",\n \"mongodb://your-connection-string\"\n ]\n ```\n\n##### Option 1: NPX (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"mongodb-lens\": {\n \"command\": \"/path/to/npx\",\n \"args\": [\n \"-y\",\n \"mongodb-lens@latest\",\n \"mongodb://your-connection-string\"\n ]\n }\n }\n}\n```\n\n##### Option 2: Docker Hub Image\n\n```json\n{\n \"mcpServers\": {\n \"mongodb-lens\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\",\n \"--network=host\",\n \"--pull=always\",\n \"furey/mongodb-lens\",\n \"mongodb://your-connection-string\"\n ]\n }\n }\n}\n```\n\n##### Option 3: Local Node.js Installation\n\n```json\n{\n \"mcpServers\": {\n \"mongodb-lens\": {\n \"command\": \"/path/to/node\",\n \"args\": [\n \"/path/to/mongodb-lens.js\",\n \"mongodb://your-connection-string\"\n ]\n }\n }\n}\n```\n\n##### Option 4: Local Docker Image\n\n```json\n{\n \"mcpServers\": {\n \"mongodb-lens\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\",\n \"--network=host\",\n \"mongodb-lens\",\n \"mongodb://your-connection-string\"\n ]\n }\n }\n}\n```\n\n### Client Setup: MCP Inspector\n\n[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a tool designed for testing and debugging MCP servers.\n\n> [!NOTE]
\n> MCP Inspector starts a proxy server on port 3000 and web client on port 5173.\n\nExample NPX usage:\n\n1. Run MCP Inspector:
\n ```console\n # Using default connection string mongodb://localhost:27017\n npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest\n\n # Using custom connection string\n npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest mongodb://your-connection-string\n\n # Using custom ports\n SERVER_PORT=1234 CLIENT_PORT=5678 npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest\n ```\n1. Open MCP Inspector: http://localhost:5173\n\nMCP Inspector should support the full range of MongoDB Lens capabilities, including autocompletion for collection names and query fields.\n\nFor more, see: [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)\n\n### Client Setup: Other MCP Clients\n\nMongoDB Lens should be usable with any MCP-compatible client.\n\nFor more, see: [MCP Documentation: Example Clients](https://modelcontextprotocol.io/clients)\n\n## Data Protection\n\nTo protect your data while using MongoDB Lens, consider the following:\n\n- [Read-Only User Accounts](#data-protection-read-only-user-accounts)\n- [Working with Database Backups](#data-protection-working-with-database-backups)\n- [Confirmation for Destructive Operations](#data-protection-confirmation-for-destructive-operations)\n- [Disabling Destructive Operations](#data-protection-disabling-destructive-operations)\n\n### Data Protection: Read-Only User Accounts\n\nWhen 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.\n\nTo 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:\n\n```js\nuse admin\n\ndb.createUser({\n user: 'readonly',\n pwd: 'eXaMpLePaSsWoRd',\n roles: [{ role: 'read', db: 'mydatabase' }]\n})\n```\n\nThen, apply those credentials to your MongoDB connection string:\n\n```txt\nmongodb://readonly:eXaMpLePaSsWoRd@localhost:27017/mydatabase\n```\n\nUsing 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.\n\n### Data Protection: Working with Database Backups\n\nWhen working with MongoDB Lens, consider connecting to a backup copy of your data hosted on a separate MongoDB instance.\n\nStart 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`).\n\nThis approach gives you a sandbox to test complex or destructive operations against without risking accidental corruption of your live data.\n\n### Data Protection: Confirmation for Destructive Operations\n\nMongoDB 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:\n\n1. First tool invocation: Returns a 4-digit confirmation token that expires after 5 minutes\n1. Second tool invocation: Executes the operation if provided with the valid token\n\nFor an example of the confirmation process, see: [Working with Confirmation Protection](#tutorial-5-working-with-confirmation-protection)\n\nTools that require confirmation include:\n\n- `drop-user`: Remove a database user\n- `drop-index`: Remove an index (potential performance impact)\n- `drop-database`: Permanently delete a database\n- `drop-collection`: Delete a collection and all its documents\n- `delete-document`: Delete one or multiple documents\n- `bulk-operations`: When including delete operations\n- `rename-collection`: When the target collection exists and will be dropped\n\nThis 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.\n\n> [!NOTE]
\n> If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to [bypass confirmation](#bypassing-confirmation-for-destructive-operations) and perform destructive operations immediately.\n\n#### Bypassing Confirmation for Destructive Operations\n\nYou might want to bypass the token confirmation system.\n\nSet the environment variable `CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS` to `true` to execute destructive operations immediately without confirmation:\n\n```console\n# Using NPX\nCONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS=true npx -y mongodb-lens@latest\n\n# Using Docker\ndocker run --rm -i --network=host --pull=always -e CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS='true' furey/mongodb-lens\n```\n\n> [!WARNING]
\n> 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.\n\n### Data Protection: Disabling Destructive Operations\n\n- [Disabling Tools](#disabling-tools)\n- [High-Risk Tools](#high-risk-tools)\n- [Medium-Risk Tools](#medium-risk-tools)\n- [Read-Only Configuration](#read-only-configuration)\n\n#### Disabling Tools\n\nMongoDB 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](#configuration-config-file):\n\n```json\n{\n \"disabled\": {\n \"tools\": [\n \"drop-user\",\n \"drop-index\",\n \"drop-database\",\n \"drop-collection\",\n \"delete-document\",\n \"bulk-operations\",\n \"rename-collection\"\n ]\n }\n}\n```\n\n#### High-Risk Tools\n\nThese tools can cause immediate data loss and should be considered for disabling in sensitive environments:\n\n- `drop-user`: Removes database users and their access permissions\n- `drop-index`: Removes indexes (can impact query performance)\n- `drop-database`: Permanently deletes entire databases\n- `drop-collection`: Permanently deletes collections and all their documents\n- `delete-document`: Removes documents matching specified criteria\n- `bulk-operations`: Can perform batch deletions when configured to do so\n- `rename-collection`: Can overwrite existing collections when using the drop target option\n\n#### Medium-Risk Tools\n\nThese tools can modify data but typically don't cause immediate data loss:\n\n- `create-user`: Creates users with permissions that could enable further changes\n- `transaction`: Executes multiple operations in a transaction (potential for complex changes)\n- `modify-document`: Inserts or updates documents which could overwrite existing data\n\n#### Read-Only Configuration\n\nFor a complete read-only configuration, disable all potentially destructive tools:\n\n```json\n{\n \"disabled\": {\n \"tools\": [\n \"drop-user\",\n \"drop-index\",\n \"create-user\",\n \"transaction\",\n \"create-index\",\n \"drop-database\",\n \"drop-collection\",\n \"delete-document\",\n \"modify-document\",\n \"bulk-operations\",\n \"create-database\",\n \"gridfs-operation\",\n \"create-collection\",\n \"rename-collection\",\n \"create-timeseries\"\n ]\n }\n}\n```\n\nThis configuration allows MongoDB Lens to query and analyze data while preventing any modifications, providing multiple layers of protection against accidental data loss.\n\n## Tutorial\n\nThis 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:\n\n1. [Start Sample Data Container](#tutorial-1-start-sample-data-container)\n1. [Import Sample Data](#tutorial-2-import-sample-data)\n1. [Connect MongoDB Lens](#tutorial-3-connect-mongodb-lens)\n1. [Example Queries](#tutorial-4-example-queries)\n1. [Working With Confirmation Protection](#tutorial-5-working-with-confirmation-protection)\n\n### Tutorial: 1. Start Sample Data Container\n\n> [!NOTE]
\n> This tutorial assumes you have [Docker](https://docs.docker.com/get-started/get-docker/) installed and running on your system.\n\n> [!IMPORTANT]
\n> If Docker is already running a container on port 27017, stop it before proceeding.\n\n1. Initialise the sample data container:
\n ```console\n docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6\n ```\n1. Verify the container is running without issue:
\n ```console\n docker ps | grep mongodb-sampledata\n ```\n\n### Tutorial: 2. Import Sample Data\n\nMongoDB provides several [sample datasets](https://www.mongodb.com/docs/atlas/sample-data/#available-sample-datasets) which we'll use to explore MongoDB Lens.\n\n1. Download the sample datasets:\n ```console
\n curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive\n ```\n1. Copy the sample datasets into your sample data container:
\n ```console\n docker cp sampledata.archive mongodb-sampledata:/tmp/\n ```\n1. Import the sample datasets into MongoDB:
\n ```console\n docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive\n ```\n\nThis will import several databases:\n\n- `sample_airbnb`: Airbnb listings and reviews\n- `sample_analytics`: Customer and account data\n- `sample_geospatial`: Geographic data\n- `sample_mflix`: Movie data\n- `sample_restaurants`: Restaurant data\n- `sample_supplies`: Supply chain data\n- `sample_training`: Training data for various applications\n- `sample_weatherdata`: Weather measurements\n\n### Tutorial: 3. Connect MongoDB Lens\n\n[Install](#installation) MongoDB Lens as per the [Quick Start](#quick-start) instructions.\n\nSet your [MCP Client](#client-setup) to connect to MongoDB Lens via: `mongodb://localhost:27017`\n\n> [!TIP]
\n> Omitting the connection string from your MCP Client configuration will default the connection string to `mongodb://localhost:27017`.\n\nExample [Claude Desktop configuration](#client-setup-claude-desktop):\n\n```json\n{\n \"mcpServers\": {\n \"mongodb-lens\": {\n \"command\": \"/path/to/npx\",\n \"args\": [\n \"-y\",\n \"mongodb-lens@latest\"\n ]\n }\n }\n}\n```\n\n### Tutorial: 4. Example Queries\n\nWith your MCP Client running and connected to MongoDB Lens, try the following example queries:\n\n- [Example Queries: Basic Database Operations](#example-queries-basic-database-operations)\n- [Example Queries: Collection Management](#example-queries-collection-management)\n- [Example Queries: User Management](#example-queries-user-management)\n- [Example Queries: Querying Data](#example-queries-querying-data)\n- [Example Queries: Schema Analysis](#example-queries-schema-analysis)\n- [Example Queries: Data Modification](#example-queries-data-modification)\n- [Example Queries: Performance & Index Management](#example-queries-performance--index-management)\n- [Example Queries: Geospatial & Special Operations](#example-queries-geospatial--special-operations)\n- [Example Queries: Export, Administrative & Other Features](#example-queries-export-administrative--other-features)\n- [Example Queries: Connection Management](#example-queries-connection-management)\n\n#### Example Queries: Basic Database Operations\n\n- _\"List all available databases\"_
\n ^{➥ Uses `list-databases` tool}\n- _\"What database am I currently using?\"_
\n ^{➥ Uses `current-database` tool}\n- _\"Switch to the sample_mflix database\"_
\n ^{➥ Uses `use-database` tool}\n- _\"Create a new database called test_db\"_
\n ^{➥ Uses `create-database` tool}\n- _\"Create another database called analytics_db and switch to it\"_
\n ^{➥ Uses `create-database` tool with switch=true}\n- _\"Drop the test_db database\"_
\n ^{➥ Uses `drop-database` tool (with confirmation)}\n\n#### Example Queries: Collection Management\n\n- _\"What collections are in the current database?\"_
\n ^{➥ Uses `list-collections` tool}\n- _\"Create a new collection named user_logs\"_
\n ^{➥ Uses `create-collection` tool}\n- _\"Drop the user_logs collection\"_
\n ^{➥ Uses `drop-collection` tool (with confirmation)}\n- _\"Rename the user_logs collection to system_logs\"_
\n ^{➥ Uses `rename-collection` tool}\n- _\"Check the data consistency in the movies collection\"_
\n ^{➥ Uses `validate-collection` tool}\n\n#### Example Queries: User Management\n\n- _\"Create a read-only user for analytics\"_
\n ^{➥ Uses `create-user` tool}\n- _\"Drop the inactive_user account\"_
\n ^{➥ Uses `drop-user` tool (with confirmation)}\n\n#### Example Queries: Querying Data\n\n- _\"Count all documents in the movies collection\"_
\n ^{➥ Uses `count-documents` tool}\n- _\"Find the top 5 movies with the highest IMDB rating\"_
\n ^{➥ Uses `find-documents` tool}\n- _\"Show me aggregate data for movies grouped by decade\"_
\n ^{➥ Uses `aggregate-data` tool}\n- _\"List all unique countries where movies were produced\"_
\n ^{➥ Uses `distinct-values` tool}\n- _\"Search for movies containing 'godfather' in their title\"_
\n ^{➥ Uses `text-search` tool}\n- _\"Find German users with last name 'müller' using proper collation\"_
\n ^{➥ Uses `collation-query` tool}\n\n#### Example Queries: Schema Analysis\n\n- _\"What's the schema structure of the movies collection?\"_
\n ^{➥ Uses `analyze-schema` tool}\n- _\"Compare the schema between users and comments collections\"_
\n ^{➥ Uses `compare-schemas` tool}\n- _\"Generate a JSON schema validator for the movies collection\"_
\n ^{➥ Uses `generate-schema-validator` tool}\n- _\"Analyze common query patterns for the movies collection\"_
\n ^{➥ Uses `analyze-query-patterns` tool}\n\n#### Example Queries: Data Modification\n\n- _\"Insert a new movie document\"_
\n ^{➥ Uses `modify-document` tool (insert operation)}\n- _\"Update all movies from 1994 to add a 'classic' flag\"_
\n ^{➥ Uses `modify-document` tool (update operation)}\n- _\"Delete all movies with zero ratings\"_
\n ^{➥ Uses `delete-document` tool (with confirmation)}\n- _\"Run these bulk operations on the movies collection\"_
\n ^{➥ Uses `bulk-operations` tool}\n\n#### Example Queries: Performance & Index Management\n\n- _\"Create an index on the title field in the movies collection\"_
\n ^{➥ Uses `create-index` tool}\n- _\"Drop the unused ratings_idx index\"_
\n ^{➥ Uses `drop-index` tool (with confirmation)}\n- _\"Explain the execution plan for finding movies from 1995\"_
\n ^{➥ Uses `explain-query` tool}\n- _\"Get statistics for the current database\"_
\n ^{➥ Uses `get-stats` tool (database target)}\n- _\"Show collection stats for the movies collection\"_
\n ^{➥ Uses `get-stats` tool (collection target)}\n\n#### Example Queries: Geospatial & Special Operations\n\n- _\"Switch to sample_geospatial database, then find all shipwrecks within 10km of coordinates [-80.12, 26.46]\"_
\n ^{➥ Uses `geo-query` tool}\n- _\"Switch to sample_mflix database, then run this Map-Reduce to calculate movie counts by year with map `'function () { emit(this.year, 1) }'` and reduce `'function (key, values) { return Array.sum(values) }'`\"_
\n ^{➥ Uses `map-reduce` tool}\n- _\"Switch to sample_analytics database, then execute a transaction to move funds between accounts\"_
\n ^{➥ Uses `transaction` tool}\n- _\"Create a time series collection for sensor readings\"_
\n ^{➥ Uses `create-timeseries` tool}\n- _\"Watch for changes in the users collection for 30 seconds\"_
\n ^{➥ Uses `watch-changes` tool}\n- _\"List all files in the images GridFS bucket\"_
\n ^{➥ Uses `gridfs-operation` tool (list operation)}\n\n#### Example Queries: Export, Administrative & Other Features\n\n- _\"Switch to sample_mflix database, then export the top 20 movies based on 'tomatoes.critic.rating' as a CSV with title, year and rating fields, output as raw csv text in a single code block\"_
\n ^{➥ Uses `export-data` tool}\n- _\"Switch to sample_analytics database, then check its sharding status\"_
\n ^{➥ Uses `shard-status` tool}\n- _\"Switch to sample_weatherdata database, and generate an interactive report on its current state\"_
\n ^{➥ Uses numerous tools}\n\n#### Example Queries: Connection Management\n\n- _\"Connect to a different MongoDB server at mongodb://localhost:27018\"_
\n ^{➥ Uses `connect-mongodb` tool}\n- _\"Connect to MongoDB Atlas instance at mongodb+srv://username:password@cluster.mongodb.net/mydb\"_
\n ^{➥ Uses `connect-mongodb` tool}\n- _\"Connect back to the original MongoDB server\"_
\n ^{➥ Uses `connect-original` tool}\n- _\"Connect to a MongoDB replica set without validating the connection\"_
\n ^{➥ Uses `connect-mongodb` tool with validateConnection=false}\n\n### Tutorial: 5. Working With Confirmation Protection\n\nMongoDB Lens includes a safety mechanism for potentially destructive operations. Here's how it works in practice:\n\n1. Request to drop a collection:
\n ```\n \"Drop the collection named test_collection\"\n ```\n1. MongoDB Lens responds with a warning and confirmation token:
\n ```\n ⚠️ DESTRUCTIVE OPERATION WARNING ⚠️\n\n You've requested to drop the collection 'test_collection'.\n\n This operation is irreversible and will permanently delete all data in this collection.\n\n To confirm, you must type the 4-digit confirmation code EXACTLY as shown below:\n\n Confirmation code: 9876\n\n This code will expire in 5 minutes for security purposes.\n ```\n1. Confirm the operation by submitting the confirmation token:
\n ```\n \"9876\"\n ```\n1. MongoDB Lens executes the operation:
\n ```\n Collection 'test_collection' has been permanently deleted.\n ```\n\nThis two-step process prevents accidental data loss by requiring explicit confirmation.\n\n> [!NOTE]
\n> If you're working in a controlled environment where data loss is acceptable, you can configure MongoDB Lens to [bypass confirmation](#bypassing-confirmation-for-destructive-operations) and perform destructive operations immediately.\n\n## Disclaimer\n\nMongoDB Lens:\n\n- is licensed under the [MIT License](./LICENSE).\n- is not affiliated with or endorsed by MongoDB, Inc.\n- is written with the assistance of AI and may contain errors.\n- is intended for educational and experimental purposes only.\n- is provided as-is with no warranty—please use at your own risk.\n\n## Support\n\nIf you've found MongoDB Lens helpful consider supporting my work through:\n\n[Buy Me a Coffee](https://www.buymeacoffee.com/furey) | [GitHub Sponsorship](https://github.com/sponsors/furey)\n\nContributions 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.\n","url","https://github.com/furey/mongodb-lens","githubRepository",{"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_95":96,"_97":98,"_100":101},"defaultBranch","main","fullName","furey/mongodb-lens","githubTreeId",104211,"language","JavaScript","name","mongodb-lens","owner",{"_92":93,"_8":94},"login","furey","6LVDLmBaOi","recentStargazers",10,"spdxLicense",{"_88":99},"MIT License","stargazers",23,"glamaJson","id",1738,"inspectable","integrations",[108],{"_109":110,"_55":116,"_8":117},"brand",{"_111":112,"_88":113,"_114":115},"logoSvgPath","M17.193 9.555c-1.264-5.58-4.252-7.414-4.573-8.115-.28-.394-.53-.954-.735-1.44-.036.495-.055.685-.523 1.184-.723.566-4.438 3.682-4.74 10.02-.282 5.912 4.27 9.435 4.888 9.884l.07.05A73.49 73.49 0 0111.91 24h.481c.114-1.032.284-2.056.51-3.07.417-.296.604-.463.85-.693a11.342 11.342 0 003.639-8.464c.01-.814-.103-1.662-.197-2.218zm-5.336 8.195s0-8.291.275-8.29c.213 0 .49 10.695.49 10.695-.381-.045-.765-1.76-.765-2.405z","MongoDB","slug","mongodb","Provides full featured access to MongoDB databases using natural language via LLMs to perform queries, run aggregations, optimize performance, and more. The server connects to MongoDB instances to allow exploration, querying, and management of databases, collections, and documents.","ryow2uz3ak","MongoDB Lens","namespace","npmPackage",{"_88":89,"_122":123},"weeklyDownloads",796,"prompts","redditPostForeignId","1jb48xy","relatedMcpServerIds",[129,130,131,132,133,134],1430,1457,1569,260,259,496,"resources","scores",{"_138":139,"_140":-5,"_141":-5},"license",100,"quality","security","simpleIcon","supportedPlatforms",[145,146],"MACOS","WINDOWS","tools","hniehmvmgn","updatedAt",["D",1742614421708],"meta",[153,155,157,164,167,169,172,175,178,181,184,186,189,192,194,196,198,200,202],{"_10":154},"MongoDB Lens | Glama",{"_156":70,"_88":55},"content",{"_158":159,"_160":161,"_162":163},"href","https://glama.ai/mcp/servers/@furey/mongodb-lens","rel","canonical","tagName","link",{"_156":118,"_165":166},"property","og:title",{"_156":70,"_165":168},"og:description",{"_156":170,"_165":171},"https://glama.ai/logo.png","og:logo",{"_156":173,"_165":174},"https://glama.ai/mcp/servers/@furey/mongodb-lens/og-image","og:image",{"_156":176,"_165":177},"630","og:image:height",{"_156":179,"_165":180},"1200","og:image:width",{"_156":182,"_165":183},"website","og:type",{"_156":159,"_165":185},"og:url",{"_156":187,"_165":188},"ChatGPT alternative for power users","og:site_name",{"_156":190,"_88":191},"summary_large_image","twitter:card",{"_156":187,"_88":193},"twitter:title",{"_156":70,"_88":195},"twitter:description",{"_156":173,"_88":197},"twitter:image",{"_156":176,"_88":199},"twitter:image:height",{"_156":179,"_88":201},"twitter:image:width",{"_203":204},"script:ld+json",{"_205":206,"_207":208},"@context","http://schema.org","@graph",[209],{"_205":210,"_211":212,"_213":214},"https://schema.org","@type","BreadcrumbList","itemListElement",[215,222,226,230],{"_211":216,"_217":218,"_88":219,"_220":221},"ListItem","item","https://glama.ai/","Glama","position",1,{"_211":216,"_217":223,"_88":224,"_220":225},"https://glama.ai/mcp","MCP",2,{"_211":216,"_217":227,"_88":228,"_220":229},"https://glama.ai/mcp/servers","Servers",3,{"_211":216,"_217":159,"_88":118,"_220":231},4,"routes/_public/mcp/servers/~namespace/~slug/_pages/_explorer/blob/~branch/~/_route",{"_234":235,"_239":81,"_43":240,"_259":260,"_261":262},"blob",{"_156":236,"_237":238},"FROM node:22-alpine\n\nWORKDIR /app\n\nCOPY package*.json ./\n\nRUN npm ci --no-fund --no-audit\n\nCOPY . .\n\nENTRYPOINT [\"node\", \"mongodb-lens.js\"]\n","fileName","Dockerfile","branch",{"_45":241,"_47":242,"_28":246,"_69":70,"_71":70,"_72":247,"_78":248,"_102":-5,"_103":104,"_105":42,"_106":251,"_88":118,"_119":93,"_120":254,"_124":-5,"_125":126,"_127":255,"_135":-5,"_136":256,"_142":-5,"_114":89,"_143":257,"_147":-5,"_8":148,"_149":258},["D",1741534522049],{"_49":243,"_58":245,"_12":60},{"_51":244},{"_53":54,"_55":56,"_12":57},[],[62,63,64,65,66,67,68],{"_74":75,"_76":77},{"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":249,"_95":96,"_97":250,"_100":101},{"_92":93,"_8":94},{"_88":99},[252],{"_109":253,"_55":116,"_8":117},{"_111":112,"_88":113,"_114":115},{"_88":89,"_122":123},[129,130,131,132,133,134],{"_138":139,"_140":-5,"_141":-5},[145,146],["D",1742614421708],"path","","treeMembers",[263,266,268,270,271,273,275,277,279,281,283],{"_259":264,"_12":265},".dockerhub","tree",{"_259":267,"_12":265},".github",{"_259":269,"_12":234},"config-create.js",{"_259":238,"_12":234},{"_259":272,"_12":234},".dockerignore",{"_259":274,"_12":234},".gitignore",{"_259":276,"_12":234},"LICENSE",{"_259":278,"_12":234},"mongodb-lens.js",{"_259":280,"_12":234},"package.json",{"_259":282,"_12":234},"package-lock.json",{"_259":284,"_12":234},"README.md","actionData","errors"]