A
security-
licenseA
qualityAn MCP server that enables users to create and manage MongoDB Atlas clusters, users, and network access through natural language commands.
Last updated -
6
20
11
MIT License
MongoDB 镜头
MongoDB Lens是一个本地模型上下文协议 (MCP) 服务器，具有通过 LLM 使用自然语言对 MongoDB 数据库进行全功能访问的功能，可以执行查询、运行聚合、优化性能等。
内容
快速入门
特征
工具
add-connection-alias：添加新的 MongoDB 连接别名aggregate-data：执行聚合管道analyze-query-patterns：分析实时查询并提出优化建议analyze-schema：自动推断集合模式bulk-operations：高效执行多个操作（破坏性操作需要确认）clear-cache：清除内存缓存以确保数据新鲜collation-query：查找具有特定语言排序规则的文档compare-schemas：比较两个集合之间的模式connect-mongodb：连接到不同的 MongoDB URIconnect-original：连接回启动时使用的原始 MongoDB URIcount-documents：统计符合指定条件的文档数量create-collection：使用自定义选项创建新集合create-database：创建一个新的数据库，并可以选择切换到该数据库create-index：创建新索引以优化性能create-timeseries：为时间数据创建时间序列集合create-user：创建具有特定角色的新数据库用户current-database：显示当前数据库上下文delete-document：删除符合指定条件的文档（需要确认）distinct-values：提取任意字段的唯一值drop-collection：从数据库中删除集合（需要确认）drop-database：删除数据库（需要确认）drop-index：从集合中删除索引（需要确认）explain-query：分析查询执行计划export-data：以 JSON 或 CSV 格式导出查询结果find-documents：使用过滤器、投影和排序运行查询generate-schema-validator：生成 JSON 模式验证器geo-query：使用各种运算符执行地理空间查询get-stats：检索数据库或集合统计信息gridfs-operation：使用 GridFS buckets 管理大文件insert-document：将一个或多个文档插入集合list-collections：浏览当前数据库中的集合list-connections：查看所有可用的 MongoDB 连接别名list-databases：查看所有可访问的数据库rename-collection：重命名现有集合（删除目标时需要确认）shard-status：查看数据库和集合的分片配置text-search：跨文本索引字段执行全文搜索transaction：在单个 ACID 事务中执行多个操作update-document：更新符合指定条件的文档use-database：切换到特定的数据库上下文validate-collection：检查数据不一致watch-changes：监控集合的实时变化
资源
collection-indexes：集合的索引信息collection-schema：集合的架构信息collection-stats：集合的性能统计信息collection-validation：集合的验证规则collections：当前数据库中的集合列表database-triggers：数据库更改流和事件触发器配置database-users：当前数据库中的数据库用户和角色databases：所有可访问数据库的列表performance-metrics：实时性能指标和分析数据replica-status：副本集状态和配置server-status：服务器状态信息stored-functions：当前数据库中存储的 JavaScript 函数
提示
aggregation-builder：逐步创建聚合管道backup-strategy：定制备份和恢复建议data-modeling：针对特定用例的 MongoDB 模式设计专家建议database-health-check：全面的数据库健康评估和建议index-recommendation：根据查询模式获取个性化索引建议migration-guide：MongoDB 版本迁移分步指南mongo-shell：生成带有解释的 MongoDB shell 命令multi-tenant-design：设计 MongoDB 多租户数据库架构query-builder：构建 MongoDB 查询的交互式指南query-optimizer：针对慢查询的优化建议schema-analysis：详细的集合模式分析及建议schema-versioning：管理 MongoDB 应用程序中的模式演变security-audit：数据库安全分析及改进建议sql-to-mongodb：将 SQL 查询转换为 MongoDB 聚合管道
其他功能
其他功能：概述
MongoDB Lens 还包含许多其他功能：
配置文件：通过
~/.mongodb-lens.[jsonc|json]进行自定义配置Env Var Overrides ：通过
process.env.CONFIG_*覆盖配置设置确认系统：破坏性操作两步验证
多个连接：定义并在命名 URI 别名之间切换
组件禁用：选择性地禁用工具、提示或资源
连接弹性：采用指数退避算法的自动重新连接
查询保障：可配置的限制和性能保护
错误处理：全面的 JSONRPC 错误代码和消息
模式推断：通过智能采样进行高效的模式分析
凭证保护：日志中的连接字符串密码混淆
内存管理：自动监控和清理大型操作
智能缓存：针对模式、索引、字段和集合进行优化缓存
向后兼容：支持现代和旧版 MongoDB 版本
其他特性：新的数据库元数据
MongoDB Lens 将metadata集合插入到它创建的每个数据库中。
该metadata集合存储包含上下文信息的单个文档，作为数据库来源的永久记录，同时确保新的和空的数据库保留在 MongoDB 的存储系统中。
{
"_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")
}
}
将自己的集合添加到新数据库后，您可以通过drop-collection工具安全地删除metadata集合：
“删除新数据库的元数据集合” ➥使用
drop-collection工具（带确认）
安装
MongoDB Lens 可以通过多种方式安装和运行：
安装：NPX
运行 MongoDB Lens 最简单的方法是使用 NPX。
首先，确保已安装 Node.js：
node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible
然后，通过 NPX 运行 MongoDB Lens：
# 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
如果您遇到npx的权限错误，请尝试在运行npx -y mongodb-lens之前运行npx clear-npx-cache （这将清除缓存并重新下载包）。
安装：Docker Hub
NOTE
Docker Hub 需要在你的系统上安装并运行Docker 。
首先，确保已安装 Docker：
docker --version # Ideally >= v27.x
然后，通过 Docker Hub 运行 MongoDB Lens：
# Using default connection string mongodb://localhost:27017
docker run --rm -i --network=host furey/mongodb-lens
# Using custom connection string
docker run --rm -i --network=host furey/mongodb-lens mongodb://your-connection-string
# Using "--pull" to keep the Docker image up-to-date
docker run --rm -i --network=host --pull=always furey/mongodb-lens
安装：来自源代码的 Node.js
克隆 MongoDB Lens 存储库：
git clone https://github.com/furey/mongodb-lens.git导航到克隆的存储库目录：
cd /path/to/mongodb-lens确保已安装 Node.js：
node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible安装 Node.js 依赖项：
npm ci启动服务器：
# Using default connection string mongodb://localhost:27017 node mongodb-lens.js # Using custom connection string node mongodb-lens.js mongodb://your-connection-string
安装：从源代码安装 Docker
NOTE
从源代码运行 Docker 需要在你的系统上安装并运行Docker 。
克隆 MongoDB Lens 存储库：
git clone https://github.com/furey/mongodb-lens.git导航到克隆的存储库目录：
cd /path/to/mongodb-lens确保已安装 Docker：
docker --version # Ideally >= v27.x构建 Docker 镜像：
docker build -t mongodb-lens .运行容器：
# 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
安装验证
要验证安装，请将以下 JSONRPC 消息粘贴到服务器的 stdio 中并运行：
{"method":"resources/read","params":{"uri":"mongodb://databases"},"jsonrpc":"2.0","id":1}
服务器应该响应 MongoDB 实例中的数据库列表，例如：
{"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 现已安装并准备接受 MCP 请求。
安装：旧版 MongoDB
如果连接到版本< 4.0的 MongoDB 实例，则最新版本的 MongoDB Lens 所使用的 MongoDB Node.js 驱动程序将不兼容。具体来说，MongoDB Node.js 驱动程序4.0.0及以上版本需要 MongoDB 4.0或更高版本。
要将 MongoDB Lens 与较旧的 MongoDB 实例一起使用，您需要使用3.x系列的 MongoDB Node.js 驱动程���版本（例如与 MongoDB 3.6兼容的3.7.4 ）。
旧 MongoDB 版本：从源代码运行
克隆 MongoDB Lens 存储库：
git clone https://github.com/furey/mongodb-lens.git导航到克隆的存储库目录：
cd /path/to/mongodb-lens修改
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 ... }安装 Node.js 依赖项：
npm install启动 MongoDB Lens：
node mongodb-lens.js mongodb://older-mongodb-instance
这将使用与您的 MongoDB 实例兼容的旧驱动程序版本。
NOTE
您可能还需要撤消此提交以重新添加useNewUrlParser和useUnifiedTopology MongoDB 配置选项。
较旧的 MongoDB 版本：使用 NPX 或 Docker
如果您更喜欢使用 NPX 或 Docker，则需要使用与兼容驱动程序一起发布的旧版本的 MongoDB Lens。
例如，MongoDB Lens 8.3.0使用 MongoDB Node.js 驱动程序3.7.4 （参见： package-lock.json ）。
要使用 NPX 运行旧版本的 MongoDB Lens，请指定版本标签：
npx -y mongodb-lens@8.3.0
对于 Docker 来说类似：
docker run --rm -i --network=host furey/mongodb-lens:8.3.0
配置
配置：MongoDB 连接字符串
服务器接受 MongoDB 连接字符串作为其唯一参数。
NPX 使用示例：
npx -y mongodb-lens@latest mongodb://your-connection-string
MongoDB 连接字符串具有以下格式：
mongodb://[username:password@]host[:port][/database][?options]
连接字符串示例：
本地连接：
mongodb://localhost:27017使用来自
admin数据库的凭据连接到mydatabase：mongodb://username:password@hostname:27017/mydatabase?authSource=admin使用其他各种选项连接到
mydatabase：mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority
如果没有提供连接字符串，服务器将尝试通过本地连接进行连接。
配置：配置文件
MongoDB Lens 支持通过 JSON 配置文件进行广泛的自定义。
配置文件是可选的。如果未提供配置文件，MongoDB Lens 将使用默认设置运行。
您只需在配置文件中包含要自定义的设置即可。MongoDB Lens 将对任何省略的值使用默认设置。
TIP
MongoDB Lens 支持.json和.jsonc （带有注释的 JSON）配置文件格式。
{
"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
}
}
}
默认情况下，MongoDB Lens 在以下位置查找配置文件：
首先是
~/.mongodb-lens.jsonc，然后回退到如果前者不存在，
~/.mongodb-lens.json
要自定义配置文件路径，请将环境变量CONFIG_PATH设置为所需的文件路径。
NPX 使用示例：
CONFIG_PATH='/path/to/config.json' npx -y mongodb-lens@latest
Docker Hub 使用示例：
docker run --rm -i --network=host --pull=always -v /path/to/config.json:/root/.mongodb-lens.json furey/mongodb-lens
配置：配置文件生成
您可以使用config:create脚本自动生成配置文件：
# 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
该脚本提取上面的示例配置文件并将其保存到： ~/.mongodb-lens.jsonc
配置文件生成：自定义路径
您可以使用CONFIG_PATH环境变量指定自定义输出位置。
如果
CONFIG_PATH没有文件扩展名，则将其视为目录并附加.mongodb-lens.jsonc如果
CONFIG_PATH以.json（而不是.jsonc）结尾，则生成的文件中删除注释
NPX 使用示例：
# 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
Node.js 使用示例：
# 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
配置：多个 MongoDB 连接
MongoDB Lens 支持配置文件中带有别名的多个 MongoDB URI，允许您使用简单名称在不同的 MongoDB 实例之间轻松切换。
要配置多个连接，请将mongoUri配置设置设置为具有别名-URI 对的对象：
{
"mongoUri": {
"main": "mongodb://localhost:27017",
"backup": "mongodb://localhost:27018",
"atlas": "mongodb+srv://username:password@cluster.mongodb.net/mydb"
}
}
使用以下配置：
列表中的第一个 URI（例如
main）在启动时成为默认连接您可以使用自然语言切换连接：
"Connect to backup"或"Connect to atlas"原始语法仍然有效：
"Connect to mongodb://localhost:27018"list-connections工具显示所有可用的连接别名
NOTE
使用命令行参数指定连接时，您可以使用完整的 MongoDB URI 或配置文件中定义的别名。
TIP
要在运行时添加连接别名，请使用add-connection-alias工具。
配置：环境变量覆盖
MongoDB Lens 支持配置设置的环境变量覆盖。
环境变量优先于配置文件设���。
配置环境变量遵循命名模式：
CONFIG_[SETTING PATH, SNAKE CASED, UPPERCASED]
覆盖示例：
配置设置 | 环境变量覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
对于环境变量值：
对于布尔设置，使用字符串值
'true'或'false'。对于数字设置，请使用字符串表示形式。
对于嵌套对象或数组，请使用 JSON 字符串。
NPX 使用示例：
CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest
Docker Hub 使用示例：
docker run --rm -i --network=host --pull=always -e CONFIG_DEFAULTS_QUERY_LIMIT='25' furey/mongodb-lens
配置：跨平台环境变量
为了在 Windows、macOS 和 Linux 上一致地使用环境变量，请考虑使用cross-env ：
全局安装跨环境：
# Using NPM npm install -g cross-env # Using Volta (see: https://volta.sh) volta install cross-env在本文档的示例中，为任何 NPX 或 Node.js 环境变量添加前缀：
# 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
客户端设置
客户端设置：Claude Desktop
要将 MongoDB Lens 与 Claude Desktop 一起使用：
打开
claude_desktop_config.json（如果不存在则创建）：macOS：
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows：
%APPDATA%\Claude\claude_desktop_config.json
根据配置选项添加 MongoDB Lens 服务器配置
重启Claude桌面
与 Claude 开始讨论您的 MongoDB 数据
Claude 桌面配置选项
对于每个选项：
将
mongodb://your-connection-string替换为您的 MongoDB 连接字符串，或者省略它以使用默认的mongodb://localhost:27017。要使用自定义配置文件，请设置
CONFIG_PATH环境变量。要包含环境变量：
对于 NPX 或 Node.js，添加带有键值对的
"env": {}，例如："command": "/path/to/npx", "args": [ "-y", "mongodb-lens@latest", "mongodb://your-connection-string" ], "env": { "CONFIG_LOG_LEVEL": "verbose" }对于 Docker 添加
-e标志，例如："command": "docker", "args": [ "run", "--rm", "-i", "--network=host", "--pull=always", "-e", "CONFIG_LOG_LEVEL=verbose", "furey/mongodb-lens", "mongodb://your-connection-string" ]
选项 1：NPX（推荐）
{
"mcpServers": {
"mongodb-lens": {
"command": "/path/to/npx",
"args": [
"-y",
"mongodb-lens@latest",
"mongodb://your-connection-string"
]
}
}
}
选项 2：Docker Hub 镜像
{
"mcpServers": {
"mongodb-lens": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--network=host",
"--pull=always",
"furey/mongodb-lens",
"mongodb://your-connection-string"
]
}
}
}
选项 3：本地 Node.js 安装
{
"mcpServers": {
"mongodb-lens": {
"command": "/path/to/node",
"args": [
"/path/to/mongodb-lens.js",
"mongodb://your-connection-string"
]
}
}
}
选项 4：本地 Docker 镜像
{
"mcpServers": {
"mongodb-lens": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--network=host",
"mongodb-lens",
"mongodb://your-connection-string"
]
}
}
}
客户端设置：MCP 检查器
MCP Inspector是一款用于测试和调试 MCP 服务器的工具。
NOTE
MCP Inspector 在端口 3000 上启动代理服务器，在端口 5173 上启动 Web 客户端。
NPX 使用示例：
运行 MCP 检查器：
# 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打开 MCP 检查器： http://localhost:5173
MCP Inspector 应该支持 MongoDB Lens 的全部功能，包括集合名称和查询字段的自动完成。
更多信息请参见： MCP 检查器
客户端设置：其他 MCP 客户端
MongoDB Lens 应该可以与任何与 MCP 兼容的客户端一起使用。
更多信息，请参阅： MCP 文档：示例客户端
数据保护
为了在使用 MongoDB Lens 时保护您的数据，请考虑以下事项：
数据保护：只读用户帐户
将 MongoDB Lens 连接到数据库时，MongoDB 连接字符串中授予用户的权限决定了可以执行的操作。当用例合适时，只读用户可以防止意外的写入或删除，确保 MongoDB Lens 可以查询数据但不能更改数据。
要进行此设置，请创建一个具有read角色的用户，该角色的作用域是目标数据库。在 MongoDB shell 中，您可以运行以下命令：
use admin
db.createUser({
user: 'readonly',
pwd: 'eXaMpLePaSsWoRd',
roles: [{ role: 'read', db: 'mydatabase' }]
})
然后，将这些凭据应用到您的 MongoDB 连接字符串：
mongodb://readonly:eXaMpLePaSsWoRd@localhost:27017/mydatabase
使用只读凭据是一种简单而有效的强制安全边界的方法，特别是当您探究模式或运行临时查询时。
数据保护：使用数据库备份
使用 MongoDB Lens 时，请考虑连接到托管在单独的 MongoDB 实例上的数据的备份副本。
首先使用mongodump生成备份。接下来，启动一个新的 MongoDB 实例（例如，在27018等其他端口上），并使用mongorestore在该实例上还原备份。运行后，将 MongoDB Lens 指向备份实例的连接字符串（例如mongodb://localhost:27018/mydatabase ）。
这种方法为您提供了一个沙箱来测试复杂或破坏性的操作，而不会冒意外损坏实时数据的风险。
数据保护：数据流注意事项
数据流考虑：数据如何在系统中流动
当使用带有远程 LLM 提供商（例如通过 Claude Desktop 的 Anthropic）的 MCP 服务器时，了解数据如何在系统中流动是保护敏感信息免遭意外泄露的关键。
当您通过 MCP 客户端发送 MongoDB 相关查询时，会发生以下情况：
NOTE
虽然此示例使用本地 MongoDB 实例，但相同的原则也适用于远程 MongoDB 实例。
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
您提交请求➥例如“显示所有 30 岁以上的用户”
您的客户将请求发送到远程 LLM➥ LLM 提供商会收到您的确切措辞以及可用的 MCP 工具及其参数的列表。
远程 LLM 解释您的请求➥ 它确定您的意图并指示客户端使用具有适当参数的特定 MCP 工具。
客户端要求 MongoDB Lens 运行该工具➥ 这通过 stdio 在您的机器上本地进行。
MongoDB Lens 查询您的 MongoDB 数据库
MongoDB Lens 检索您的 MongoDB 查询结果
MongoDB Lens 将数据发送回客户端➥ 客户端接收由 MongoDB Lens 格式化的结果。
客户端将数据转发到远程 LLM➥ LLM 提供程序可以看到 MongoDB Lens 返回的精确数据。
远程 LLM 处理数据➥它可能会进一步总结或格式化结果。
远程LLM将最终回复发送给客户端➥客户端向您显示答案。
远程 LLM 提供商会同时看到您的原始请求和来自 MongoDB Lens 的完整响应。如果您的数据库包含敏感字段（例如密码、个人信息等），除非您采取预防措施，否则这些数据可能会被无意中传输给远程提供商。
数据流注意事项：使用投影保护敏感数据
为了防止敏感数据被发送到远程 LLM 提供商，请在使用find-documents 、 aggregate-data或export-data等工具时使用投影的概念。投影允许您指定在查询结果中包含或排除哪些字段，从而确保敏感信息保留在本地。
投影用法示例：
“显示所有超过 30 岁的用户，但使用投影隐藏他们的密码。” ➥ 使用带有投影的
find-documents工具
数据流注意事项：连接别名和密码
使用add-connection-alias工具添加新的连接别名时，如果您使用的是远程 LLM 提供程序，请避免将别名添加到包含密码的 URI。由于您的请求会发送到 LLM，因此 URI 中的任何密码都可能被泄露。建议您在 MongoDB Lens配置文件中定义包含密码的别名，这样别名会保留在本地，不会传输到 LLM。
数据流考虑：本地设置以实现最大安全性
虽然超出了本文档的讨论范围，但为了获得最高级别的数据隐私，请考虑使用本地 MCP 客户端搭配本地托管的 LLM 模型。这种方法将所有请求和数据保留在本地环境中，从而消除了敏感信息被发送到远程提供商的风险。
数据保护：破坏性操作的确认
MongoDB Lens 针对潜在的破坏性操作实现了基于令牌的确认系统，需要两步过程来执行可能导致不受控制的数据丢失的工具：
第一次工具调用：返回一个 4 位数的确认令牌，该令牌在 5 分钟后过期
第二次工具调用：如果提供了有效的令牌，则执行操作
有关确认过程的示例，请参阅：使用确认保护
需要确认的工具包括：
drop-user：删除数据库用户drop-index：删除索引（可能影响性能）drop-database：永久删除数据库drop-collection：删除集���及其所有文档delete-document：删除一个或多个文档bulk-operations：包括删除操作时rename-collection：当目标集合存在时将被删除
此保护机制旨在防止因输入错误或误操作导致意外数据丢失。它就像一道安全网，确保您在执行可能造成危害的操作之前了解其后果。
NOTE
如果您在可以接受数据丢失的受控环境中工作，则可以配置 MongoDB Lens 以绕过确认并立即执行破坏性操作。
绕过破坏性操作的确认
您可能想要绕过令牌确认系统。
将环境变量CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS设置为true ，即可立即执行破坏性操作而无需确认：
# 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
禁用确认令牌会移除一项重要的安全机制。强烈建议仅在可接受数据丢失的受控环境中使用此选项，例如开发或测试环境。禁用此选项风险自负。
数据保护：禁用破坏性操作
禁用工具
MongoDB Lens 包含几个可以修改或删除数据的工具。要禁用特定工具，请将它们添加到配置文件中的disabled.tools数组中：
{
"disabled": {
"tools": [
"drop-user",
"drop-index",
"drop-database",
"drop-collection",
"delete-document",
"bulk-operations",
"rename-collection"
]
}
}
NOTE
还可以通过disabled.resources和disabled.prompts设置禁用资源和提示。
高风险工具
这些工具可能会导致立即的数据丢失，应考虑在敏感环境中禁用：
drop-user：删除数据库用户及其访问权限drop-index：删除索引（可能会影响查询性能）drop-database：永久删除整个数据库drop-collection：永久删除集合及其所有文档delete-document：删除符合指定条件的文档bulk-operations：配置后可以执行批量删除rename-collection：使用 drop target 选项时可以覆盖现有集合
中等风险工具
这些工具可以修改数据，但通常不会导致立即的数据丢失：
create-user：创建具有可进行进一步更改的权限的用户transaction：在一个事务中执行多个操作（可能存在复杂的变化）update-document：更新可能覆盖现有数据的文档
只读配置
要获得完整的只读配置，请禁用所有可能具有破坏性的工具：
{
"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"
]
}
}
此配置允许 MongoDB Lens 查询和分析数据，同时防止任何修改，提供多层保护以防止意外数据丢失。
选择性组件启用
除了禁用组件之外，还可以使用配置文件中的enabled设置来精确指定应启用哪些组件（隐式禁用所有其他组件）：
{
"enabled": {
"tools": [
"use-database",
"find-documents",
"count-documents",
"aggregate-data"
]
},
"disabled": {
"resources": true,
"prompts": true
}
}
IMPORTANT
如果组件同时出现在enabled和disabled列表中，则enabled设置优先。
教程
以下教程将指导您设置包含示例数据的 MongoDB 容器，然后使用 MongoDB Lens 通过自然语言查询与其进行交互：
教程：1. 启动示例数据容器
NOTE
本教程假设您已在系统上安装并运行Docker 。
IMPORTANT
如果 Docker 已在端口 27017 上运行容器，请先停止它再继续。
初始化示例数据容器：
docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6验证容器是否正常运行：
docker ps | grep mongodb-sampledata
教程：2. 导入示例数据
MongoDB 提供了几个示例数据集，我们将使用它们来探索 MongoDB Lens。
下载示例数据集：
curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive将示例数据集复制到示例数据容器中：
docker cp sampledata.archive mongodb-sampledata:/tmp/将示例数据集导入 MongoDB：
docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive
这将导入几个数据库：
sample_airbnb：Airbnb 房源和评论sample_analytics：客户和账户数据sample_geospatial：地理数据sample_mflix：电影数据sample_restaurants：餐厅数据sample_supplies：供应链数据sample_training：各种应用的训练数据sample_weatherdata：天气测量
教程：3. 连接 MongoDB Lens
设置您的MCP 客户端通过以下方式连接到 MongoDB Lens： mongodb://localhost:27017
TIP
从 MCP 客户端配置中省略连接字符串将使连接字符串默认为mongodb://localhost:27017 。
Claude 桌面配置示例：
{
"mcpServers": {
"mongodb-lens": {
"command": "/path/to/npx",
"args": [
"-y",
"mongodb-lens@latest"
]
}
}
}
教程：4. 示例查询
在 MCP 客户端运行并连接到 MongoDB Lens 的情况下，尝试以下示例查询：
示例查询：基本数据库操作
“列出所有数据库” ➥使用
list-databases工具“我目前使用什么数据库？” ➥ 使用
current-database工具“切换到 sample_mflix 数据库” ➥ 使用
use-database工具���创建一个名为 test_db 的新数据库” ➥使用
create-database工具“创建另一个名为 analytics_db 的数据库并切换到它” ➥ 使用
create-database工具并设置 switch=true“Drop test_db” ➥使用
drop-database工具（需确认）
示例查询：集合管理
“当前数据库中有哪些馆藏？” ➥ 使用
list-collections工具“创建 user_logs 集合” ➥ 使用
create-collection工具“将 user_logs 重命名为 system_logs” ➥ 使用
rename-collection工具“Drop system_logs” ➥使用
drop-collection工具（需确认）“检查电影集合中的数据一致性” ➥使用
validate-collection工具
示例查询：用户管理
“创建只读用户进行分析” ➥使用
create-user工具“删除非活动用户帐户” ➥使用
drop-user工具（需确认）
示例查询：查询数据
“统计电影集合中的所有文档” ➥使用
count-documents工具“查找 IMDB 评分最高的 5 部电影” ➥ 使用
find-documents工具“显示按年代分组的电影汇总数据” ➥ 使用
aggregate-data工具“列出所有制作电影的特定国家” ➥ 使用
distinct-values工具“搜索片名包含《教父》的电影” ➥ 使用
text-search工具“使用适当的排序规则查找姓氏为 müller 的德国用户” ➥ 使用
collation-query工具
示例查询：模式分析
“电影集合的架构是什么样的？” ➥ 使用
analyze-schema工具“比较用户和评论模式” ➥使用
compare-schemas工具“为电影集合生成一个模式验证器” ➥使用
generate-schema-validator工具“分析电影集合的常见查询模式” ➥使用
analyze-query-patterns工具
示例查询：数据修改
“插入新电影文档：<您的字段数据>” ➥使用
insert-document工具“更新 1994 年以来的所有电影，添加‘经典’标记” ➥ 使用
update-document工具“删除所有零评分的电影” ➥使用
delete-document工具（需确认）“对电影集合运行这些批量操作：<你的 JSON 数据>” ➥ 使用
bulk-operations工具
TIP
对于专门的 MongoDB 操作（如数组操作、按位操作或其他复杂更新），请通过update-document工具的update和options参数使用 MongoDB 的本机运算符。
示例查询：性能和索引管理
“在电影集合的标题字段上创建索引” ➥使用
create-index工具“删除 ratings_idx 索引” ➥ 使用
drop-index工具（需确认）“解释查找 1995 年电影的执行计划” ➥ 使用
explain-query工具“获取当前数据库的统计信息” ➥ 使用
get-stats工具，目标为数据库“显示电影收藏的统计信息” ➥ 使用带有 target=collection 的
get-stats工具
示例查询：地理空间和特殊操作
“切换到 sample_geospatial db，然后查找坐标 [-80.12, 26.46] 10 公里范围内的所有沉船” ➥ 使用
geo-query工具“切换到 sample_analytics db，然后执行交易以在账户之间转移资金： ➥ 使用
transaction工具“为传感器读数创建时间序列集合” ➥使用
create-timeseries工具“观察用户集合中的变化 30 秒” ➥ 使用
watch-changes工具“列出图像 GridFS 存储桶中的所有文件” ➥ 使用
gridfs-operation工具并指定 operation=list
示例查询：导出、管理和其他功能
切换到 sample_mflix db，然后根据‘tomatoes.critic.rating’将排名前 20 的电影导出为 CSV 文件，其中包含标题、年份和评级字段（在单个代码块中输出）” ➥ 使用
export-data工具“切换到 sample_analytics db，然后检查其分片状态” ➥ 使用
shard-status工具“清除集合缓存” ➥ 使用带有 target=collections 的
clear-cache工具“清除所有缓存” ➥ 使用
clear-cache工具“切换到 sample_weatherdata db，然后生成关于其当前状态的交互式报告” ➥ 使用多种工具
示例查询：连接管理
“连接到 mongodb://localhost:27018” ➥ 使用
connect-mongodb工具“连接到 mongodb+srv://username: ➥使用
connect-mongodb工具“连接回原始 mongodb 实例” ➥ 使用
connect-original工具“连接到副本集而不验证连接：<副本集详细信息>” ➥ 使用
connect-mongodb工具并设置validateConnection=false“为 mongodb://username:password@prod-server:27017/mydb 添加连接别名‘prod’” ➥ 使用
add-connection-alias工具
教程：5. 使用确认保护
MongoDB Lens 包含针对潜在破坏性操作的安全机制。其实际运作方式如下：
删除集合的请求：
"Drop the collection named test_collection"MongoDB Lens 以警告和确认令牌进行响应：
⚠️ 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.通过提交确认令牌来确认操作：
"9876"MongoDB Lens 执行操作：
Collection 'test_collection' has been permanently deleted.
此两步过程通过要求明确确认来防止意外的数据丢失。
NOTE
如果您在可以接受数据丢失的受控环境中工作，则可以配置 MongoDB Lens 以绕过确认并立即执行破坏性操作。
测试套件
MongoDB Lens 包含一个测试套件，用于验证工具、资源和提示的功能。
测试套件：运行测试
测试套件需要一个CONFIG_MONGO_URI环境变量，可以将其设置为：
MongoDB 连接字符串（例如
mongodb://localhost:27017）mongodb-memory-server（用于内存测试）
# 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
为了方便起见，可以使用以下脚本来运行测试：
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
测试套件会创建临时数据库和集合，这些数据库和集合会在测试完成后清理。
测试套件：命令行选项
选项 | 描述 |
| 列出所有可用的测试但不运行它们 |
| 按名称运行特定测试（以逗号分隔） |
| 运行特定组中的所有测试（以逗号分隔） |
| 运行匹配模式的测试（以逗号分隔） |
测试套件：示例
# 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
免责声明
MongoDB 透视图：
是根据MIT 许可证授权的。
与 MongoDB, Inc. 没有任何关联或认可。
是在人工智能的帮助下编写的，可能包含错误。
仅用于教育和实验目的。
按原样提供，不提供任何担保 - 请自行承担使用风险。
支持
如果您发现 MongoDB Lens 有帮助，请考虑通过以下方式支持我的工作：
贡献帮助我继续开发和改进这个工具，让我可以投入更多的时间来添加新功能，并确保它仍然是社区的宝贵资源。
Related MCP Servers
- -security-license-qualityAn MCP server that enables large language models to interact directly with MongoDB databases, allowing them to query collections, inspect schemas, and manage data through natural language.Last updated -109MIT License
- -security-license-qualityOpen source MCP server specializing in easy, fast, and secure tools for Databases.Last updated -11,234Apache 2.0
- -security-license-qualityMongoDB MCP Server by CDataLast updated -MIT License