mongodb-mcp-setup

MongoDB MCP 服务设置

本技能将指导用户配置 MongoDB MCP 服务，以便与 Agent 客户端配合使用。

概述

MongoDB MCP 服务需要身份验证。用户有三种选择：

1. 连接字符串（选项 A）：直接连接到特定集群

   • 快速设置单个集群
   • 需要设置 MDB_MCP_CONNECTION_STRING 环境变量

2. 服务账户凭据（选项 B）：MongoDB Atlas Admin API 访问权限

   • 推荐 Atlas 用户使用——简化身份验证和数据访问
   • 可访问 Atlas Admin API，并通过 atlas-connect-cluster 动态连接集群
   • 无需手动管理数据库用户凭据
   • 需要设置 MDB_MCP_API_CLIENT_ID 和 MDB_MCP_API_CLIENT_SECRET 环境变量

3. Atlas Local（选项 C）：使用 Docker 进行本地开发

   • 最适合本地测试——无需任何配置
   • 在 Docker 中本地运行 Atlas，需要安装 Docker
   • 无需凭据或云集群访问权限

这是一份交互式分步指南。Agent 会检测用户的环境并提供相应的说明，但绝不会索取或处理凭据——用户应在步骤 5 中直接将凭据添加到 shell 配置文件或 Agent 客户端配置中。每当在步骤 3a 和 3b 中提到凭据时，都要向用户明确说明这一点。

步骤 0：检测客户端

首先，确定用户正在运行哪个 Agent 客户端。这将决定步骤 1 和步骤 5 中的凭据配置方式。

运行：

env | grep "^CODEX_"

• 如果不存在 CODEX_* 变量 → 用户正在运行基于 shell 的客户端（Claude、Cursor、Gemini CLI、Copilot CLI 等）。通过 shell 配置文件中的环境变量配置凭据。
• 如果存在任何 CODEX_* 变量 → 用户正在运行 Codex。凭据存储在 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）中，而非 shell 环境变量中。从 Finder、Launchpad 或 Windows 开始菜单启动桌面应用时，它不会继承 shell 环境变量。

在之后的每个步骤中都要沿用此客户端类型（Codex 或基于 shell 的客户端）。

步骤 1：检查现有配置

检查凭据是否已配置。

对于基于 shell 的客户端——检查当前环境：

env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'

对于 Codex——搜索 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）：

grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'

判断方式（两种情况均适用）：

• 如果出现 MDB_MCP_CONNECTION_STRING → 已配置连接字符串身份验证
• 如果同时出现 MDB_MCP_API_CLIENT_ID 和 MDB_MCP_API_CLIENT_SECRET → 已配置服务账户身份验证。如果只出现其中一个，则视为配置不完整。
• 如果出现 MDB_MCP_READ_ONLY → 已启用只读模式

部分配置的处理：

• 用户想在现有设置中启用只读模式（已有身份验证，但没有只读标志）→ 跳至步骤 4
• 用户想切换身份验证方式 → 说明应先删除旧凭据（Codex 用户从 config.toml 中删除，基于 shell 的客户端用户从 shell 配置文件中删除），然后继续步骤 2–5
• 用户想更新凭据 → 跳至步骤 5

重要提示：如果用户想执行 Atlas Admin API 操作（管理集群、创建用户、使用性能顾问），但只有 MDB_MCP_CONNECTION_STRING，请说明他们需要服务账户凭据，并主动引导其完成设置。

步骤 2：展示配置选项

如果不存在有效配置，请展示以下选项：

连接字符串（选项 A） — 适用于：

• 访问单个集群
• 已有数据库凭据
• 自托管 MongoDB，或不需要 Atlas Admin API

服务账号凭据（选项 B） — 适用于：

• MongoDB Atlas 用户（推荐）
• 在多个集群之间切换
• 访问 Atlas Admin API（集群管理、创建用户、性能监控）

Atlas Local（选项 C） — 适用于：

• 无需云端配置的本地开发/测试
• 使用 Docker，配置最快，无需凭据

询问用户想选择哪个选项。

步骤 3a：设置连接字符串

如果用户选择选项 A：

3a.1：说明如何查找连接字符串

说明如何获取连接字符串以及在哪里获取：

对于 MongoDB Atlas：

1. 前往 cloud.mongodb.com
2. 选择集群 → 点击 Connect
3. 选择 Drivers 或 Shell → 复制连接字符串
4. 将 <username> 和 <password> 替换为数据库用户凭据

对于自托管 MongoDB：

• 连接字符串通常由 DBA 配置，或配置在应用程序配置文件中
• 格式：mongodb://username:password@host:port/database

预期格式：

• mongodb://username:password@host:port/database
• mongodb+srv://username:[email protected]/database
• mongodb://host:port（本地，无身份验证）

继续执行步骤 4（确定只读访问权限）。

步骤 3b：设置服务账号

如果用户选择选项 B：

3b.1：引导用户创建 Atlas 服务账号

引导用户创建 MongoDB Atlas 服务账号：

完整文档：https://www.mongodb.com/docs/mcp-server/prerequisites/

引导用户完成以下关键步骤：

1. 前往 MongoDB Atlas — cloud.mongodb.com
2. 从页面顶部附近的 ORGANIZATION 部分中选择组织
3. 在左侧栏中前往 “Project Identity and Access” → Applications → Create Service Account
4. 设置权限 — 授予 Organization Member 或 Project Owner 权限（确切的权限映射请参阅文档）
5. 生成凭据 — 创建 Client ID 和 Secret
   • ⚠️ Client Secret 只会显示一次 — 离开页面前请立即保存
6. 记下这两个值 — 步骤 5 需要 Client ID 和 Client Secret

3b.2：配置 API 访问列表

⚠️ 重要：用户必须将自己的 IP 地址添加到服务账号的 API 访问列表中，否则所有 Atlas Admin API 操作都会失败。

步骤：

1. 在服务账号详情页面中，找到 API Access List
2. 点击 Add Access List Entry
3. 添加当前 IP 地址。请尽可能使用特定 IP 或 CIDR 范围。
   • ⚠️ 0.0.0.0/0 允许任何 IP 访问，存在重大安全风险。 仅在最后不得已时用于临时测试，并在测试后立即移除。绝不可在生产环境中使用。
4. 保存更改

这比全局 Network Access 设置更安全，因为它只影响 API 访问，不影响数据库连接。

继续执行步骤 4（确定只读访问权限）。

步骤 3c：设置 Atlas Local

如果用户选择选项 C：

3c.1：检查 Docker 安装情况

验证是否已安装 Docker：

docker info

如果尚未安装，请引导用户前往：https://www.docker.com/get-started

3c.2：确认设置完成

Atlas Local 无需凭据 — 用户现在即可开始使用：

• 创建部署：atlas-local-create-deployment
• 列出部署：atlas-local-list-deployments
• 使用 Docker 即可开箱执行所有操作

跳过步骤 4 和 5（无需配置），并继续执行步骤 6（后续步骤）。

步骤 4：确定只读还是读写访问权限

仅适用于选项 A 和 B。选项 C 请跳至步骤 6。

询问用户需要只读还是读写访问权限：

• 读写（默认）：拥有完整数据访问权限，可以修改数据

  • 适用于：开发、测试、管理任务

• 只读：仅可读取数据，不能修改数据

  • 适用于：保障生产数据安全、报告、合规

如果选择只读：在步骤 5 的凭据代码片段中加入只读标志。 如果选择读写：省略该标志（默认为读写）。

继续执行步骤 5（配置凭据）。

步骤 5：配置凭据

不要询问或处理凭据——提供确切的说明，让用户可以直接添加凭据。

5.1：添加凭据

对于基于 shell 的客户端——将凭据存放在专用的 ~/.mcp-env 文件中（不要直接存放在 shell 配置文件中），然后从配置文件中加载该文件。这样可以避免凭据出现在默认情况下通常对组用户或所有用户可读的文件中，也能防止意外将凭据提交到 git。

对于 Codex——添加到 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）。

向用户展示相应的代码片段：

对于连接字符串（选项 A）：

基于 shell 的客户端（~/.mcp-env）：

export MDB_MCP_CONNECTION_STRING="<paste-your-connection-string-here>"

Codex（config.toml）：

[mcp_servers.mongodb.env]
MDB_MCP_CONNECTION_STRING = "<paste-your-connection-string-here>"

对于服务账号（选项 B）：

基于 shell 的客户端（~/.mcp-env）：

export MDB_MCP_API_CLIENT_ID="<paste-your-client-id-here>"
export MDB_MCP_API_CLIENT_SECRET="<paste-your-client-secret-here>"

Codex（config.toml）：

[mcp_servers.mongodb.env]
MDB_MCP_API_CLIENT_ID = "<paste-your-client-id-here>"
MDB_MCP_API_CLIENT_SECRET = "<paste-your-client-secret-here>"

如果在步骤 4 中选择了只读，还需添加：

基于 shell 的客户端：在 ~/.mcp-env 中添加 export MDB_MCP_READ_ONLY="true"。

Codex：在同一个 [mcp_servers.mongodb.env] 部分中添加 MDB_MCP_READ_ONLY = "true"。

⚠️ config.toml 和 ~/.mcp-env 都以纯文本形式存储。不要将它们提交到版本控制中。

5.2：完成设置（仅适用于基于 shell 的客户端）

限制 ~/.mcp-env 的权限：

# adjust for windows if needed
chmod 600 ~/.mcp-env

在 shell 配置文件（例如 ~/.zshrc）中添加 source ~/.mcp-env。根据检测到的 shell 进行调整（例如，对于 fish：使用 bass source ~/.mcp-env 或 set -x；对于 PowerShell：改为对 .ps1 文件执行点源操作）。

如有需要，可运行 echo $SHELL 检测 shell 和配置文件。

5.3：验证

基于 shell 的客户端——先重新加载配置文件，然后验证：

source ~/.zshrc  # adjust to match the profile file
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'

Codex：

# adjust path if on Windows
grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'

预期输出会显示已配置的密钥，其值会被隐藏为 [set]。如果没有显示任何内容，请检查凭据是否已保存；对于基于 shell 的客户端，还要确认配置文件已重新加载。

继续执行步骤 6（后续步骤）。

步骤 6：后续步骤

对于选项 A 和 B（连接字符串／服务账号）：

1. 重启 Agent 客户端：

   • 基于 shell 的客户端：完全退出客户端，然后运行 source <profile-file> 加载新变量，并在同一个终端会话中重新打开客户端，使其继承环境变量。
   • Codex：完全退出并重新启动应用。无需终端会话——凭据来自 config.toml。

2. 验证 MCP 服务：重启后，通过执行 MongoDB 操作进行测试。

3. 使用工具：

   • 选项 A：可使用直接数据库访问工具
   • 选项 B：还可使用 Atlas Admin API 工具和 atlas-connect-cluster
   • 重要提示（选项 B）：确保你的 IP 地址已添加到服务账号的 API 访问列表中，否则所有 API 调用都会失败

对于选项 C（Atlas Local）：

1. 已可使用：无需重启或配置！

2. 后续步骤：

   • 创建部署：atlas-local-create-deployment
   • 列出部署：atlas-local-list-deployments
   • 连接后使用标准数据库操作

故障排除

• 执行 source 后变量未显示（基于 Shell 的客户端）：检查配置文件路径，并确认文件已保存
• 客户端未读取变量：确保完全重启（退出并重新打开），而不是仅重新加载
• Codex 桌面应用未读取凭据：如果通过 Finder、Launchpad 或 Windows「开始」菜单启动，Codex 不会继承 .zshrc/.zprofile/PowerShell 配置文件中的 Shell 环境变量。请改用 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）（参见步骤 5）
• 连接字符串格式无效：重新检查格式；必须以 mongodb:// 或 mongodb+srv:// 开头
• Atlas Admin API 错误（选项 B）：确认你的 IP 地址已添加到服务账号的 API 访问列表中
• 只读模式未生效：检查是否已设置 MDB_MCP_READ_ONLY——Codex 需在 config.toml 的 [mcp_servers.mongodb.env] 下设置；基于 Shell 的客户端则需通过 env | grep ^MDB_MCP_READ_ONLY 检查
• fish/PowerShell：语法不同——请使用 set -x（fish）或 $env:（PowerShell），而不是 export