mongodb-mcp-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MongoDB MCP Server Setup

MongoDB MCP 服务器配置指南

This skill guides users through configuring the MongoDB MCP server for use with an agentic client.

本指南将引导用户配置MongoDB MCP服务器，以供Agent客户端使用。

Overview

概述

The MongoDB MCP server requires authentication. Users have three options:

Connection String (Option A): Direct connection to a specific cluster
- Quick setup for single cluster
- Requires
```
MDB_MCP_CONNECTION_STRING
```
  environment variable
Service Account Credentials (Option B): MongoDB Atlas Admin API access
- Recommended for Atlas users - simplifies authentication and data access
- Access to Atlas Admin API and dynamic cluster connection via
```
atlas-connect-cluster
```
- No manual DB user credential management
- Requires
```
MDB_MCP_API_CLIENT_ID
```
  and
```
MDB_MCP_API_CLIENT_SECRET
```
  environment variables
Atlas Local (Option C): Local development with Docker
- Best for local testing - zero configuration required
- Runs Atlas locally in Docker, requires Docker installed
- No credentials or cloud cluster access

This is an interactive step-by-step guide. The agent detects the user's environment and provides tailored instructions, but never asks for or handles credentials — users add those directly to their shell profile in Step 5. Make this clear to the user whenever credentials come up in Steps 3a and 3b.

MongoDB MCP服务器需要身份验证，用户有三种配置选项：

连接字符串（选项A）：直接连接到指定集群
- 单集群快速配置方案
- 需要配置
```
MDB_MCP_CONNECTION_STRING
```
  环境变量
服务账号凭证（选项B）：MongoDB Atlas 管理API访问权限
- 推荐Atlas用户使用：可简化身份验证和数据访问流程
- 支持Atlas管理API访问，可通过
```
atlas-connect-cluster
```
  动态连接集群
- 无需手动管理数据库用户凭证
- 需要配置
```
MDB_MCP_API_CLIENT_ID
```
  和
```
MDB_MCP_API_CLIENT_SECRET
```
  环境变量
Atlas Local（选项C）：基于Docker的本地开发环境
- 最适合本地测试：无需任何配置
- 在Docker中本地运行Atlas，需要预先安装Docker
- 无需凭证，也不访问云端集群

本指南为交互式分步指引，Agent会检测用户环境并提供定制化说明，但绝对不会索要或处理用户凭证——用户需在第5步自行将凭证添加到shell配置文件中。在第3a和3b步涉及凭证相关内容时，请明确向用户告知这一点。

Step 1: Check Existing Configuration

步骤1：检查现有配置

Before starting the setup, check if the user already has the required environment variables configured.

Run this command to check for existing configuration (masking values to avoid exposing credentials):

bash

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

Interpretation:

If
```
MDB_MCP_CONNECTION_STRING
```
is set → connection string auth is configured
If both
```
MDB_MCP_API_CLIENT_ID
```
and
```
MDB_MCP_API_CLIENT_SECRET
```
are set → service account auth is configured. If only one is set, treat it as incomplete.
If
```
MDB_MCP_READ_ONLY=true
```
→ read-only mode is enabled

Partial Configuration Handling:

User wants to add read-only to existing setup (has auth, no
```
MDB_MCP_READ_ONLY
```
) → skip to Step 4
User wants to switch authentication methods → explain they should remove the old variables from their shell profile first, then proceed with Steps 2–5
User wants to update credentials → skip to Step 5 (profile editing instructions)

Important: If the user wants an Atlas Admin API action (managing clusters, creating users, performance advisor) but only has

MDB_MCP_CONNECTION_STRING

, explain they need service account credentials and offer to walk through setup.

开始配置前，请先检查用户是否已经配置了所需的环境变量。

运行以下命令检查现有配置（掩码处理避免暴露凭证）：

bash

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

结果解读：

如果
```
MDB_MCP_CONNECTION_STRING
```
已设置 → 连接字符串身份验证已配置
如果
```
MDB_MCP_API_CLIENT_ID
```
和
```
MDB_MCP_API_CLIENT_SECRET
```
均已设置 → 服务账号身份验证已配置。如果仅设置了其中一个，视为配置不完整
如果
```
MDB_MCP_READ_ONLY=true
```
→ 已启用只读模式

部分配置处理规则：

用户想要为现有配置添加只读权限（已有身份验证配置，无
```
MDB_MCP_READ_ONLY
```
） → 直接跳转到步骤4
用户想要切换身份验证方式 → 说明需要先从shell配置文件中删除旧的变量，再按步骤2-5操作
用户想要更新凭证 → 直接跳转到步骤5（配置文件编辑说明）

重要提示：如果用户需要使用Atlas管理API功能（管理集群、创建用户、性能顾问等）但仅配置了

MDB_MCP_CONNECTION_STRING

，需说明需要服务账号凭证，并可提供配置引导。

Step 2: Present Configuration Options

步骤2：展示配置选项

If no valid configuration exists, present the options:

Connection String (Option A) — Best for:

Single cluster access
Existing database credentials
Self-hosted MongoDB or no Atlas Admin API needs

Service Account Credentials (Option B) — Best for:

MongoDB Atlas users (recommended)
Multi-cluster switching
Atlas Admin API access (cluster management, user creation, performance monitoring)

Atlas Local (Option C) — Best for:

Local development/testing without cloud setup
Fastest setup with Docker, no credentials required

Ask the user which option they'd like to proceed with.

如果没有检测到有效配置，向用户展示可选方案：

连接字符串（选项A） 适合以下场景：

仅需要访问单个集群
已有数据库凭证
使用自托管MongoDB，或不需要Atlas管理API功能

服务账号凭证（选项B） 适合以下场景：

MongoDB Atlas用户（推荐方案）
需要切换多个集群
需要使用Atlas管理API功能（集群管理、用户创建、性能监控）

Atlas Local（选项C） 适合以下场景：

无需云端配置的本地开发/测试场景
已有Docker环境，希望最快完成配置，无需凭证

询问用户想要选择哪种配置方案。

Step 3a: Connection String Setup

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

If the user chooses Option A:

如果用户选择选项A：

3a.1: Explain How to Find the Connection String

3a.1：说明获取连接字符串的方法

Explain where and how to obtain their connection string:

For MongoDB Atlas:

Go to cloud.mongodb.com
Select your cluster → click Connect
Choose Drivers or Shell → copy the connection string
Replace
```
<username>
```
and
```
<password>
```
with your database user credentials

For self-hosted MongoDB:

The connection string is typically configured by your DBA or in your application config

Format:

mongodb://username:password@host:port/database

Expected formats:

mongodb://username:password@host:port/database

mongodb+srv://username:password@cluster.mongodb.net/database

```
mongodb://host:port
```
(local, no auth)

Proceed to Step 4 (Determine Read-Only Access).

说明获取连接字符串的位置和步骤：

MongoDB Atlas用户：

访问 cloud.mongodb.com
选择你的集群 → 点击 Connect
选择 Drivers 或 Shell → 复制连接字符串
将
```
<username>
```
和
```
<password>
```
替换为你的数据库用户凭证

自托管MongoDB用户：

连接字符串通常由DBA配置，或可在应用配置中找到

格式：

mongodb://username:password@host:port/database

预期格式：

mongodb://username:password@host:port/database

mongodb+srv://username:password@cluster.mongodb.net/database

```
mongodb://host:port
```
（本地无验证环境）

继续执行步骤4（确定读写权限）。

Step 3b: Service Account Setup

步骤3b：服务账号配置

If the user chooses Option B:

如果用户选择选项B：

3b.1: Guide Through Atlas Service Account Creation

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

Direct the user to create a MongoDB Atlas Service Account:

Full documentation: https://www.mongodb.com/docs/mcp-server/prerequisites/

Walk them through the key steps:

Navigate to MongoDB Atlas — cloud.mongodb.com
Go to Access Manager → Service Accounts → Create Service Account
Set Permissions — Grant Organization Member or Project Owner (see docs for exact permission mappings)
Generate Credentials — Create Client ID and Secret
- ⚠️ The Client Secret is shown only once — save it immediately before leaving the page
Note both values — you'll need Client ID and Client Secret for Step 5

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

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

引导用户完成核心步骤：

访问MongoDB Atlas — cloud.mongodb.com
进入访问管理器 → 服务账号 → 创建服务账号
设置权限 — 授予组织成员或项目所有者权限（可查看文档了解具体权限映射）
生成凭证 — 创建Client ID和Secret
- ⚠️ Client Secret仅会显示一次 — 离开页面前请立即保存
记录两个值 — 步骤5需要用到Client ID和Client Secret

3b.2: API Access List Configuration

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

⚠️ CRITICAL: The user MUST add their IP address to the service account's API Access List, or all Atlas Admin API operations will fail.

Steps:

On the service account details page, find API Access List
Click Add Access List Entry
Add your current IP address. Use a specific IP or CIDR range whenever possible.
- ⚠️ 0.0.0.0/0
  allows access from any IP — this is a significant security risk. Only use it as a last resort for temporary testing and remove it immediately afterward. It should never be used in production.
Save changes

This is more secure than global Network Access settings as it only affects API access, not database connections.

Proceed to Step 4 (Determine Read-Only Access).

⚠️ 关键注意事项：用户必须将自己的IP地址添加到服务账号的API访问列表中，否则所有Atlas管理API操作都会失败。

操作步骤：

在服务账号详情页，找到 API访问列表
点击 添加访问列表条目
添加你当前的IP地址，尽可能使用具体IP或CIDR范围
- ⚠️ 0.0.0.0/0
  允许来自任意IP的访问，存在极大安全风险，仅可作为临时测试的最后方案使用，使用后需立即删除，禁止在生产环境使用
保存更改

该配置比全局网络访问设置更安全，因为它仅影响API访问，不影响数据库连接。

继续执行步骤4（确定读写权限）。

Step 3c: Atlas Local Setup

步骤3c：Atlas Local配置

If the user chooses Option C:

如果用户选择选项C：

3c.1: Check Docker Installation

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

Verify Docker is installed:

bash

docker info

If not installed, direct them to: https://www.docker.com/get-started

验证Docker是否已安装：

bash

docker info

如果未安装，引导用户访问：https://www.docker.com/get-started

3c.2: Confirm Setup Complete

3c.2：确认配置完成

Atlas Local requires no credentials — the user is ready to go:

Create deployments:
```
atlas-local-create-deployment
```
List deployments:
```
atlas-local-list-deployments
```
All operations work out of the box with Docker

Skip Steps 4 and 5 (no configuration needed) and proceed to Step 6 (Next Steps).

Atlas Local无需任何凭证，用户已可以直接使用：

创建部署：
```
atlas-local-create-deployment
```
查看部署列表：
```
atlas-local-list-deployments
```
所有功能可在Docker环境下开箱即用

跳过步骤4和5（无需额外配置），直接执行步骤6（后续操作）。

Step 4: Determine Read-Only vs Read-Write Access

步骤4：确定只读/读写权限

Only applies to Options A and B. Skip to Step 6 for Option C.

Ask whether they want read-only or read-write access:

Read-Write (default): Full data access, modifications allowed
- Best for: Development, testing, administrative tasks
Read-Only: Data reads only, no modifications
- Best for: Production data safety, reporting, compliance

If read-only: include

export MDB_MCP_READ_ONLY="true"

in the profile snippet in Step 5. If read-write: omit

MDB_MCP_READ_ONLY

(defaults to read-write).

Proceed to Step 5 (Update Shell Profile).

仅适用于选项A和B，选项C直接跳转到步骤6。

询问用户想要使用只读权限还是读写权限：

读写权限（默认）：完整数据访问权限，允许修改数据
- 适用场景：开发、测试、管理任务
只读权限：仅可读取数据，不可修改
- 适用场景：生产数据安全保障、报表生成、合规场景

如果选择只读：在步骤5的配置片段中添加

export MDB_MCP_READ_ONLY="true"

如果选择读写：省略

MDB_MCP_READ_ONLY

配置（默认为读写模式）

继续执行步骤5（更新shell配置文件）。

Step 5: Update Shell Profile

步骤5：更新shell配置文件

Help the user add the environment variables to their shell profile. Do not ask for or handle credentials — provide exact instructions so the user can add them directly.

帮助用户将环境变量添加到shell配置文件中。不要索要或处理用户凭证，提供明确的操作指引让用户自行添加。

5.1: Detect Shell and Profile File

5.1：检测shell和配置文件路径

If the user is on Windows, assume PowerShell but ask the user to confirm. For Unix/macOS, detect the shell to determine the correct profile file by running:

bash

echo $SHELL

Based on the result, identify the appropriate profile file using your training data. If unsure which shell or profile they are using, ask them to specify the path.

如果用户使用Windows系统，默认使用PowerShell，但需请用户确认。对于Unix/macOS系统，运行以下命令检测shell类型以确定正确的配置文件：

bash

echo $SHELL

根据返回结果识别对应的配置文件，如果无法确定用户使用的shell或配置文件，请让用户指定路径。

5.2: Show the Exact Snippet to Add

5.2：展示需要添加的配置片段

Tell the user to store credentials in a dedicated

~/.mcp-env

file (not directly in their shell profile). This keeps credentials out of files that are often group/world readable by default and prevents accidentally committing them to git. Make sure to adapt the path in the instructions to be in the same folder as the shell profile file.

Step 1: Create/edit

~/.mcp-env

(e.g.

nano ~/.mcp-env

) and add:

For Connection String (Option A):

bash

undefined

告知用户将凭证存储在专用的

~/.mcp-env

文件中（不要直接写在shell配置文件里），这样可以避免凭证出现在默认权限为组/全局可读的文件中，防止意外提交到git仓库。请根据shell配置文件的路径调整指引中的路径。

第一步：创建/编辑

~/.mcp-env

（例如执行

nano ~/.mcp-env

），添加以下内容：

连接字符串方案（选项A）：

bash

undefined

MongoDB MCP Server Configuration

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


**For Service Account (Option B):**

```bash

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


**服务账号方案（选项B）：**

```bash

MongoDB MCP Server Configuration (Atlas Service Account)

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


**If read-only was chosen (Step 4), also add:**

```bash
export MDB_MCP_READ_ONLY="true"

Step 2: Restrict permissions on the file so only the owner can read it:

bash

chmod 600 ~/.mcp-env # adapt command for Windows if needed

Step 3: Source the file from the shell profile. Tell the user to open their profile file (e.g.

code ~/.zshrc

nano ~/.zshrc

) and add this line:

bash

source ~/.mcp-env

Adjust syntax for the detected shell (e.g. for fish:

bass source ~/.mcp-env

or set variables directly with

set -x

; for PowerShell: dot-source a

.ps1

file instead).

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


**如果在步骤4选择了只读权限，额外添加：**

```bash
export MDB_MCP_READ_ONLY="true"

第二步：修改文件权限，仅允许所有者读取：

bash

chmod 600 ~/.mcp-env # Windows系统可调整对应命令

第三步：在shell配置文件中引入该文件。告知用户打开他们的配置文件（例如

code ~/.zshrc

、

nano ~/.zshrc

），添加以下行：

bash

source ~/.mcp-env

根据检测到的shell调整语法（例如fish shell使用

bass source ~/.mcp-env

或直接用

set -x

设置变量；PowerShell使用点语法引入

.ps1

文件）。

5.3: After Editing — Reload and Verify

5.3：编辑完成后 — 重载配置并验证

Once the user has saved the file, provide the commands to reload and verify:

Reload the profile:

bash

source ~/.zshrc   # adjust path to match their profile file

Verify the variables are set (masking values to avoid exposing credentials):

bash

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

Expected output should show the variable name(s) they just added, each with

=[set]

. If nothing appears, check that

source ~/.mcp-env

is in the profile file, the profile was reloaded, and

~/.mcp-env

was saved.

Proceed to Step 6 (Next Steps).

用户保存文件后，提供重载和验证的命令：

重载配置文件：

bash

source ~/.zshrc   # 调整路径匹配用户的配置文件

验证变量是否已设置（掩码处理避免暴露凭证）：

bash

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

预期输出会显示用户刚添加的变量名，每个变量后带

=[set]

。如果没有输出，请检查

source ~/.mcp-env

是否已添加到配置文件、配置是否已重载、

~/.mcp-env

是否已保存。

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

Step 6: Next Steps

步骤6：后续操作

For Options A & B (Connection String / Service Account):

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

Restart the agentic client: Fully quit the client, then in your terminal run
```
source <profile-file>
```
(e.g.
```
source ~/.zshrc
```
, adjust command and path based on the user shell) to load the new variables into the current shell session. Open the client from that same shell session so it inherits the environment.
Verify MCP Server: After restart, test by performing a MongoDB operation.
Using the Tools:
- Option A: Direct database access tools available
- Option B: Additionally has Atlas Admin API tools and
```
atlas-connect-cluster
```
- Important (Option B): Ensure your IP is in the service account's API Access List or all API calls will fail

重启Agent客户端：完全退出客户端，然后在终端执行
```
source <配置文件路径>
```
（例如
```
source ~/.zshrc
```
，根据用户shell调整命令和路径），将新变量加载到当前shell会话中，从该shell会话启动客户端以继承环境变量。
验证MCP服务器：重启后，执行一个MongoDB操作测试是否正常。
工具使用说明：
- 选项A：可使用直接数据库访问工具
- 选项B：额外支持Atlas管理API工具和
```
atlas-connect-cluster
```
  功能
- 选项B重要提示：确保你的IP已添加到服务账号的API访问列表中，否则所有API调用都会失败

For Option C (Atlas Local):

选项C（Atlas Local）：

Ready to use: No restart or configuration needed!
Next steps:
- Create deployments:
```
atlas-local-create-deployment
```
- List deployments:
```
atlas-local-list-deployments
```
- Use standard database operations once connected

已可直接使用：无需重启或额外配置！
后续操作：
- 创建部署：
```
atlas-local-create-deployment
```
- 查看部署列表：
```
atlas-local-list-deployments
```
- 连接后可使用标准数据库操作

Troubleshooting

故障排查

Variables not appearing after
source
: Check the profile file path and confirm the file was saved
Client doesn't pick up variables: Ensure full restart (quit + reopen), not just a reload
Invalid connection string format: Re-check the format; must start with
```
mongodb://
```
or
```
mongodb+srv://
```
Atlas Admin API errors (Option B): Verify your IP is in the service account's API Access List

Read-only mode not working: Check

MDB_MCP_READ_ONLY=true

is set — run

env | grep ^MDB_MCP_READ_ONLY

fish/PowerShell: Syntax differs — use
```
set -x
```
(fish) or
```
$env:
```
(PowerShell) instead of
```
export
```

执行
```
source
```
后变量未显示：检查配置文件路径，确认文件已保存
客户端未读取到变量：确保完全重启（退出后重新打开），而不是仅重载
连接字符串格式无效：重新检查格式，必须以
```
mongodb://
```
或
```
mongodb+srv://
```
开头
Atlas管理API报错（选项B）：验证你的IP已添加到服务账号的API访问列表中
只读模式不生效：检查
```
MDB_MCP_READ_ONLY=true
```
是否已设置，执行
```
env | grep ^MDB_MCP_READ_ONLY
```
查看
fish/PowerShell语法问题：使用
```
set -x
```
（fish）或
```
$env:
```
（PowerShell）代替
```
export
```