Klavis 仓库 MongoDB MCP Server 实战指南：连接 Atlas 与本地数据库、配置安全策略与索引校验

Klavis 仓库 MongoDB MCP Server 实战指南连接 Atlas 与本地数据库、配置安全策略与索引校验【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇技术指南以 Klavis 仓库中 mcp_servers/mongodb/README.md 为核心结合仓库内 TypeScript 源码系统讲解 MongoDB MCP Server 的能力边界、六种启动方式、完整配置项、Atlas 服务账号接入与最小权限模型。读完本文你将掌握在 VS Code、Cursor、Claude Desktop 等 MCP 客户端中配置 MongoDB 服务器并通过只读模式、工具禁用清单与索引校验等机制安全地让 AI Agent 操作 MongoDB 数据。项目概述一个同时覆盖 Atlas 与数据库两个层面的 MCP 服务器MongoDB MCP Server 是一个基于 Model Context Protocol 的服务器实现让 AI Agent如 Claude、Cursor 等能够以标准化工具调用的方式与 MongoDB 数据库和 MongoDB Atlas 云服务交互。它不是一个查询封装器而是同时具备两条能力线MongoDB Atlas 管理线组织、项目、集群、访问清单、数据库用户、告警等资源的创建与查看MongoDB 数据操作线对数据库的增删改查、聚合、索引、元数据与统计信息读取。从本仓库的 package.json 可以看到该服务器基于modelcontextprotocol/sdk构建依赖 MongoDB 官方驱动mongodb、mongosh的服务提供层mongosh/service-provider-node-driver用于统一执行查询与 explain 等操作、mongodb-schema用于集合结构推断以及express用于 HTTP 传输当前仓库内的版本为0.2.0。源码完整存放于 mcp_servers/mongodb/src 目录下核心入口为 index.ts 与 server.ts。需要特别注意的是服务器在未配置 MongoDB 连接串或 Atlas API 凭据时不会启动。这是设计使然——它要求使用者在启动前就明确自己的数据来源。环境与前置条件根据 README运行该服务器需要满足Node.js至少20.19.0若使用 v22 版本则需 22.12.0v23 及以上任意版本均可。这与 package.json 中engines字段声明的^20.19.0 || ^22.12.0 || 23.0.0完全一致。凭证二选一一条 MongoDB 连接串Connection String可直接连接本地实例或 Atlas 集群Atlas API 服务账号Service Account凭据用于启用 Atlas 管理类工具。验证 Node 版本node -v快速开始六种启动方式README 提供了 6 种启动路径。默认安全约定所有示例默认携带--readOnly以保证数据只读访问如需写操作请移除该参数。方式一连接串作为命令行参数{ mcpServers: { MongoDB: { command: npx, args: [ -y, mongodb-mcp-server, --connectionString, mongodb://localhost:27017/myDatabase, --readOnly ] } } }连接串可以指向任何 MongoDB 集群无论是本地实例还是 Atlas 集群mongodbsrv://形式。方式二Atlas API 服务账号凭据作为命令行参数{ mcpServers: { MongoDB: { command: npx, args: [ -y, mongodb-mcp-server, --apiClientId, your-atlas-service-accounts-client-id, --apiClientSecret, your-atlas-service-accounts-client-secret, --readOnly ] } } }使用该方式前必须先按下文Atlas API 接入章节完成服务账号创建。方式三独立服务命令行参数不经过 MCP 客户端直接以 npx 启动npx -y mongodb-mcp-server --apiClientIdyour-atlas-service-accounts-client-id --apiClientSecretyour-atlas-service-accounts-client-secret --readOnly方式四独立服务环境变量npx -y mongodb-mcp-server --readOnly连接串或 Atlas 凭据通过环境变量注入变量名见下文配置表可先在 shell 中export后再启动也可在 MCP 配置文件的env字段中声明。方式五Docker 运行Docker 方式提供隔离环境且无需本地安装 Node.js。mongodb/mongodb-mcp-server:latest官方镜像可通过环境变量完成全部配置A. 无任何配置服务器将等待后续工具调用传入连接信息docker run --rm -i \ mongodb/mongodb-mcp-server:latestB. 携带 MongoDB 连接串docker run --rm -i \ -e MDB_MCP_CONNECTION_STRINGmongodbsrv://username:passwordcluster.mongodb.net/myDatabase \ -e MDB_MCP_READ_ONLYtrue \ mongodb/mongodb-mcp-server:latestC. 携带 Atlas API 凭据docker run --rm -i \ -e MDB_MCP_API_CLIENT_IDyour-atlas-service-accounts-client-id \ -e MDB_MCP_API_CLIENT_SECRETyour-atlas-service-accounts-client-secret \ -e MDB_MCP_READ_ONLYtrue \ mongodb/mongodb-mcp-server:latestD. 在 MCP 配置文件中以 docker 为 command{ mcpServers: { MongoDB: { command: docker, args: [ run, --rm, -e, MDB_MCP_READ_ONLYtrue, -i, mongodb/mongodb-mcp-server:latest ] } } }携带连接串与 Atlas 凭据的 Docker 配置写法同理只需在args中追加对应的-e KEYvalue对。本仓库自建镜像的差异若基于仓库内 Dockerfile 自行构建两阶段构建node:22-alpine编译、node:22-slim运行镜像默认设置了MDB_MCP_TRANSPORThttp、MDB_MCP_HTTP_HOST0.0.0.0、MDB_MCP_HTTP_PORT5000即默认以 HTTP 传输监听 5000 端口与 npx 默认的 stdio 传输不同接入客户端时需按 HTTP 方式连接。方式六以 HTTP 服务器运行服务器默认使用stdio传输适合绝大多数 MCP 客户端。当需要从 Web 客户端访问或在指定端口暴露服务时可使用 Streamable HTTP 传输npx -y mongodb-mcp-server --transport http默认监听http://127.0.0.1:3000可自定义主机与端口npx -y mongodb-mcp-server --transport http --httpHost0.0.0.0 --httpPort8080--httpHost默认127.0.0.1HTTP 服务器绑定主机--httpPort默认3000HTTP 服务器端口。安全警告HTTP 传输支持远程连接但不建议在未实现认证与安全措施的生产环境使用。README 建议至少做到在网关/反向代理层实现认证、使用 HTTPS/TLS 加密、部署在防火墙后或私有网络、实现限流且绝不直接暴露到公网。HTTP 传输还涉及两个超时参数idleTimeoutMs默认 600000ms即 10 分钟客户端空闲断开时间与notificationTimeoutMs默认 540000ms即 9 分钟客户端感知断连的通知超时。工具能力全景Atlas 工具与数据库工具工具按来源分为两个类别在源码中分别位于 src/tools/atlas 与 src/tools/mongodb 目录并各自通过 atlas/tools.ts 与 mongodb/tools.ts 注册到服务器。MongoDB Atlas 工具需配置 Atlas API 凭据工具说明atlas-list-orgs列出 MongoDB Atlas 组织atlas-list-projects列出 MongoDB Atlas 项目atlas-create-project创建新的 Atlas 项目atlas-list-clusters列出 Atlas 集群atlas-inspect-cluster检查指定 Atlas 集群详情atlas-create-free-cluster创建免费层 Atlas 集群atlas-connect-cluster连接 Atlas 集群atlas-inspect-access-list检查可访问集群的 IP/CIDR 范围atlas-create-access-list配置集群的 IP/CIDR 访问清单atlas-list-db-users列出 Atlas 数据库用户atlas-create-db-user创建 Atlas 数据库用户atlas-list-alerts列出项目下的 Atlas 告警这 12 个工具与源码中AtlasTools数组逐一对应。它们只有在配置了apiClientId/apiClientSecret时才会注册生效。MongoDB 数据库工具需可用的连接工具说明connect连接 MongoDB 实例find对集合执行 find 查询aggregate对集合执行聚合管道count统计集合中文档数量insert-one插入单条文档insert-many批量插入文档create-index为集合创建索引update-one更新单条文档update-many批量更新文档rename-collection重命名集合delete-one删除单条文档delete-many批量删除文档drop-collection删除集合drop-database删除数据库list-databases列出所有数据库list-collections列出指定数据库的所有集合collection-indexes描述集合的索引collection-schema描述集合的文档结构collection-storage-size获取集合大小MBdb-stats返回数据库统计信息版本差异说明README 工具清单与当前仓库 src/tools/mongodb/tools.ts 注册的 20 个工具存在少量出入——本仓库源码实际还包含explain查询计划分析、create-collection创建集合、logs读取日志三个元数据/创建类工具同时insert-one、update-one、delete-one在当前源码中由insertMany、updateMany、deleteMany的统一实现覆盖。请以你实际部署版本的tools/list返回为准。从源码看每个工具都继承了 src/tools/tool.ts 中的ToolBase抽象类通过categorymongodb/atlas与operationTypemetadata/read/create/delete/update/connect两个维度声明自身属性这为下文的安全控制机制只读模式、工具禁用、注解提示提供了基础。以find工具为例src/tools/mongodb/read/find.ts其输入参数为filter查询过滤条件、projection投影、limit默认 10、sort排序1 升序 / -1 降序返回结果以 BSON EJSON 序列化输出——与db.collection.find()的语义保持一致。配置详解优先级、选项表与安全开关配置优先级README 明确配置来源的优先级从高到低为命令行参数CLI环境变量该优先级在 src/common/config.ts 中有直接实现config { ...defaults, ...getEnvConfig(), ...getCliConfig() }即先铺默认值再用环境变量覆盖最后用命令行参数覆盖。完整配置选项表CLI 选项环境变量默认值说明apiClientIdMDB_MCP_API_CLIENT_ID未设置Atlas API 客户端 ID运行 Atlas 工具必需apiClientSecretMDB_MCP_API_CLIENT_SECRET未设置Atlas API 客户端密钥运行 Atlas 工具必需connectionStringMDB_MCP_CONNECTION_STRING未设置MongoDB 连接串若未设置需先调用connect工具才能操作数据loggersMDB_MCP_LOGGERSdisk,mcp逗号分隔的日志输出目标可选mcp、disk、stderrlogPathMDB_MCP_LOG_PATH见下文说明日志存储目录disabledToolsMDB_MCP_DISABLED_TOOLS未设置禁用的工具名 / 操作类型 / 类别数组readOnlyMDB_MCP_READ_ONLYfalse为 true 时仅允许 read、connect、metadata 操作indexCheckMDB_MCP_INDEX_CHECKfalse为 true 时强制查询必须走索引拒绝全集合扫描telemetryMDB_MCP_TELEMETRYenabled设为disabled可关闭遥测上报transportMDB_MCP_TRANSPORTstdiostdio或httphttpPortMDB_MCP_HTTP_PORT3000HTTP 端口httpHostMDB_MCP_HTTP_HOST127.0.0.1HTTP 绑定主机idleTimeoutMsMDB_MCP_IDLE_TIMEOUT_MS600000客户端空闲断连超时仅 http 传输notificationTimeoutMsMDB_MCP_NOTIFICATION_TIMEOUT_MS540000客户端感知断连的通知超时仅 http 传输补充源码级默认细节见 config.ts 的defaults对象apiBaseUrl默认指向 Atlas 控制台地址connectOptions默认值为readConcern: local、readPreference: secondaryPreferred、writeConcern: majority、timeoutMS: 30000——即默认优先从从节点读、多数派写、操作超时 30 秒。环境变量解析还支持类型推断true/false被解析为布尔值纯数字被解析为数值含逗号的值被解析为数组。日志选项Logger Optionsloggers控制日志去向可用值mcp将日志发送给 MCP 客户端需客户端/传输支持disk写入磁盘文件存放于logPath指定目录stderr输出到标准错误流便于调试或容器内使用。默认disk,mcp。默认磁盘日志位置Windows%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logsmacOS/Linux~/.mongodb/mongodb-mcp/.app-logs可用logPath覆盖。示例export MDB_MCP_LOGGERSdisk,stderrnpx -y mongodb-mcp-server --loggers mcp stderr禁用工具Disabled ToolsdisabledTools接受三类取值类别category或操作类型operation type或具体工具名。环境变量用逗号分隔命令行参数用空格分隔export MDB_MCP_DISABLED_TOOLScreate,update,delete,atlas,collectionSchemanpx -y mongodb-mcp-server --disabledTools create update delete atlas collectionSchema类别取值atlasAtlas 工具如列出集群、创建集群等mongodb数据库工具如 find、aggregate 等。操作类型取值create创建类工具创建集群、插入文档等update更新类工具更新文档、重命名集合等delete删除类工具删除文档、删集合等read读取类工具find、aggregate、list clusters 等metadata元数据读取类工具list databases、list collections、collection schema 等connect连接/切换连接的工具。若禁用connect则必须在启动时通过配置提供连接串。源码层面的过滤逻辑位于 src/tools/tool.ts 的verifyAllowed()按只读模式 → 类别 → 操作类型 → 工具名的顺序逐一判断被禁用的工具直接不注册到 MCP 服务器register返回false并在日志中记录Prevented registration of ...信息。只读模式Read-Only ModereadOnlytrue时服务器仅注册read、connect、metadata三类操作的工具所有create/update/delete类工具都不会注册。适用于允许 AI 分析数据但禁止任何数据或基础设施修改的场景。export MDB_MCP_READ_ONLYtruenpx -y mongodb-mcp-server --readOnly注意源码中的细节connect类工具在只读模式下仍然保留用于切换连接目标这与 README 的说明一致。启用后日志中会提示哪些工具因该限制被阻止注册。索引检查模式Index Check ModeindexChecktrue时查询操作必须使用索引执行全集合扫描COLLSCAN的查询会被拒绝用于强制保证查询性能。实现位于 src/helpers/indexCheck.ts对查询先执行explain(queryPlanner)解析winningPlan的阶段识别IXSCAN、COUNT_SCAN、IDHACK等索引扫描阶段为通过识别COLLSCAN为拒绝并递归检查深层inputStage若 explain 本身失败如权限问题则记录警告但不阻断查询避免误伤正常请求。export MDB_MCP_INDEX_CHECKtruenpx -y mongodb-mcp-server --indexCheck被拒绝时返回错误信息例如提示collection scan (COLLSCAN)并建议使用explain工具分析查询计划、用collection-indexes查看现有索引。该机制在find、aggregate、count、update、delete等读路径工具中均有接入。遥测Telemetry服务器默认启用遥测向 MongoDB 上报匿名使用数据工具调用名、耗时、成功/失败、启动时长等见 src/telemetry 目录可通过以下任一方式关闭export MDB_MCP_TELEMETRYdisablednpx -y mongodb-mcp-server --telemetry disabledexport DO_NOT_TRACK1Atlas API 接入服务账号与最小权限模型要使用 Atlas 管理工具需在 MongoDB Atlas 创建服务账号Service Account步骤如下创建服务账号登录 Atlas 控制台进入 Access Manager Organization Access选择 Add New Applications Service Accounts填写名称、描述与过期时间例如 MCP, MCP Server Access, 7 days并只分配业务所需的最小权限点击 Create。保存客户端凭据创建完成后页面会展示 Client ID 与 Client SecretClient Secret 只显示一次务必立即保存。添加访问清单条目将你的出口 IP 地址加入 API 访问清单。配置服务器通过前文任一方式设置apiClientId与apiClientSecret。权限速查表按操作选择最安全的角色你想做的事应分配的最安全角色位置列出组织/项目Org Member 或 Org Read Only组织级创建新项目Org Project Creator组织级查看项目中的集群/数据库Project Read Only项目级创建/管理项目中的集群Project Cluster Manager项目级管理项目访问清单Project IP Access List Admin项目级管理数据库用户Project Database Access Admin项目级两条安全原则优先使用项目级角色且只授权给需要管理或查看的具体项目除非需要对组织内全部项目与设置拥有完整管理权否则避免授予 Organization Owner。三种配置方法汇总与 MCP 配置文件示例方法一环境变量所有环境变量以MDB_MCP_为前缀后接大写加下划线的选项名# 设置 Atlas API 凭据服务账号 export MDB_MCP_API_CLIENT_IDyour-atlas-service-accounts-client-id export MDB_MCP_API_CLIENT_SECRETyour-atlas-service-accounts-client-secret # 设置自定义 MongoDB 连接串 export MDB_MCP_CONNECTION_STRINGmongodbsrv://username:passwordcluster.mongodb.net/myDatabase export MDB_MCP_LOG_PATH/path/to/logs方法二命令行参数npx -y mongodb-mcp-server --apiClientIdyour-atlas-service-accounts-client-id --apiClientSecretyour-atlas-service-accounts-client-secret --connectionStringmongodbsrv://username:passwordcluster.mongodb.net/myDatabase --logPath/path/to/logs --readOnly --indexCheck方法三MCP 配置文件客户端侧连接串 环境变量{ mcpServers: { MongoDB: { command: npx, args: [-y, mongodb-mcp-server], env: { MDB_MCP_CONNECTION_STRING: mongodbsrv://username:passwordcluster.mongodb.net/myDatabase } } } }Atlas 凭据 环境变量{ mcpServers: { MongoDB: { command: npx, args: [-y, mongodb-mcp-server], env: { MDB_MCP_API_CLIENT_ID: your-atlas-service-accounts-client-id, MDB_MCP_API_CLIENT_SECRET: your-atlas-service-accounts-client-secret } } } }连接串 命令行参数{ mcpServers: { MongoDB: { command: npx, args: [ -y, mongodb-mcp-server, --connectionString, mongodbsrv://username:passwordcluster.mongodb.net/myDatabase, --readOnly ] } } }Atlas 凭据 命令行参数{ mcpServers: { MongoDB: { command: npx, args: [ -y, mongodb-mcp-server, --apiClientId, your-atlas-service-accounts-client-id, --apiClientSecret, your-atlas-service-accounts-client-secret, --readOnly ] } } }提示不同 MCP 客户端的配置文件语法存在差异如 Windsurf、VS Code、Claude Desktop、Cursor接入前请查阅你所用客户端的 MCP 配置文档获取最新语法要求。源码级原理启动校验、资源暴露与工具注册启动时的配置校验src/server.ts 的validateConfig()在连接传输前执行一系列校验transport必须为stdio或httptelemetry必须为enabled或disabledhttpPort必须在 1–65535 之间loggers不能为空、不能重复、取值必须合法若配置了连接串则启动时即建立 MongoDB 连接失败会直接拒绝启动若配置了 Atlas 凭据则启动时校验访问令牌校验失败但连接串有效时仍允许启动。这正是 README 所述未配置凭证则服务器不启动的实现来源。config 资源随时查看服务器配置状态服务器注册了一个名为config的 MCP 资源URI 为config://config返回当前telemetry、logPath、connectionString、connectOptions、atlas凭据是否已配置的 JSON 信息。Agent 可通过该资源快速判断 MongoDB 工具与 Atlas 工具当前是否可用避免在未配置连接时盲目调用工具。工具注解与动态注册每个工具在注册时依据operationType生成 MCP 工具注解annotationsread/metadata/connect类标记readOnlyHint: true、destructiveHint: falsedelete类标记readOnlyHint: false、destructiveHint: true。这些注解会随工具列表下发给客户端帮助 Agent 在调用前理解工具是否具有破坏性。从本仓库源码构建本仓库 mcp_servers/mongodb 目录包含完整 TypeScript 源码、package.json、Dockerfile 与tsconfig.json。如需本地构建可在仓库根目录执行依赖安装与构建后以node dist/index.js启动构建产物入口与package.json中bin字段的mongodb-mcp-server一致。由于该服务器以npx方式运行时默认采用 stdio 传输请确保 MCP 客户端使用npx -y mongodb-mcp-server作为 command并按上文示例传入所需参数或环境变量。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考