atlas-mcp-server

Name: atlas-mcp-server
Author: mongodb-labs

本地服务

github.com/mongodb-labs数据库1.2k今天更新

代码仓库

关于 atlas-mcp-server

atlas-mcp-server 将 AI Agent 和其他 MCP 客户端连接到 MongoDB 数据库及 Atlas，提供数据库与 Atlas 操作，并支持只读模式、多种认证和部署方式。

主要功能

01查询并聚合集合数据
02查看模式、索引和统计信息
03创建、更新及删除数据库对象
04使用 MongoDB URI 或 Atlas 凭据连接
05本地运行或通过 Docker 运行

适用场景

01探索集合并执行筛选查询
02检查索引与数据库统计信息
03通过 MCP 客户端管理文档和集合

MCP 相关

向 MCP 客户端提供 MongoDB 数据库和 Atlas 操作工具，包括查询、聚合、元数据检查及数据变更。服务可在本地运行，Atlas 也提供托管远程选项。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

启动命令npx -y mongodb-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmongodb-mcp-serverstdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填
connectionId	string	是
database	string	是
pipeline	array	是
responseBytesLimit	number	否

详细介绍

MongoDB MCP 服务

用于与 MongoDB 数据库和 MongoDB Atlas 交互的模型上下文协议服务。

快速开始

使用 MongoDB 官方 AI Agent 插件

MongoDB MCP Server 随附 MongoDB 官方 AI Agent 插件。可用的插件如下：

mongodb-atlas — 通过 OAuth 连接到由 MongoDB 托管的 Atlas MCP 服务。无需在本地运行任何程序，这是从 AI Agent 连接到 MongoDB Atlas 的推荐方式：

Cursor：市场
VSCode：打开扩展视图（⇧⌘X / Ctrl+Shift+X），搜索 @agentPlugins，然后安装 mongodb-atlas。
Claude：市场
Codex：打开 /plugins 并安装 mongodb-atlas。
GitHub Copilot CLI：运行 copilot plugin install mongodb-atlas。
Grok：在 Grok Build 中打开 /marketplace 并安装 mongodb-atlas。

mongodb — 在本地运行 MongoDB MCP 服务，并连接到任意自管理部署：

Cursor：市场
Claude：市场
Gemini：市场
Codex：运行 codex plugin marketplace add mongodb/agent-skills，然后打开 /plugins 并安装 mongodb。
GitHub Copilot CLI：运行 copilot plugin install mongodb。
Grok：在 Grok Build 中打开 /marketplace 并安装 mongodb。

使用设置脚本

你可以运行以下命令，手动设置本地 MCP 服务：

npx -y mongodb-mcp-server@latest setup

此命令将引导你完成交互式设置流程，包括配置 MongoDB 连接字符串或 Atlas API 凭据。

如需了解更高级的设置选项，请参阅下方的手动设置部分。

使用 MongoDB MCP Server 设置技能

你可以添加并使用 MongoDB MCP Server 设置技能，通过 AI Agent 配置本地 MCP 服务。

npx skills add https://github.com/mongodb/agent-skills --skill mongodb-mcp-setup

使用手动配置

有关如何手动配置 MongoDB MCP Server 的说明，请参阅手动设置。

前置条件

说明

对 Node 20.x 的支持已弃用，并将在未来版本中移除。请升级到 Node 22.13 或更高版本。有关迁移详情，请参阅 https://nodejs.org/en/blog/migrations/v20-to-v22。

Node.js
- 至少为 v22.13.0。使用 node -v 检查。
MongoDB 连接字符串或 Atlas API 凭据。
- 使用 Atlas 工具需要 Service Accounts Atlas API 凭据。你可以在 MongoDB Atlas 中创建服务账户，并使用其凭据进行身份验证。详情请参阅 Atlas API 访问。
- 如果你有 MongoDB 连接字符串，可以直接使用它连接到 MongoDB 实例。

手动设置

🔒 安全建议 1： 使用 Atlas API 凭据时，请务必仅向服务账号授予所需的最低权限。详情请参阅 Atlas API Permissions。

🔒 安全建议 2： 为增强安全性，我们强烈建议使用环境变量传递连接字符串和 API 凭据等敏感配置，而不是使用命令行参数。命令行参数可能会显示在进程列表中，也可能记录在系统的各个位置，从而导致机密信息泄露。使用环境变量处理敏感信息更加安全。

大多数 MCP 客户端都需要创建或修改配置文件，才能添加 MCP 服务。

注意：不同客户端的配置文件语法可能有所不同。请参阅以下链接，了解最新的预期语法：

默认安全提示： 以下所有示例默认包含 --readOnly，以确保安全地只读访问数据。如果需要启用写入操作，请移除 --readOnly。

选项 1：连接字符串

你可以通过环境变量传递连接字符串，请确保使用有效的用户名和密码。

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

注意：连接字符串可以配置为连接到任何 MongoDB 集群，无论是本地实例还是 Atlas 集群。

选项 2：连接到 MongoDB Atlas 托管的 MCP 服务

使用 MongoDB Atlas 时，建议为你的 AI Agent 安装 mongodb-atlas plugin，该插件会自动处理 OAuth 身份验证。

如需手动配置，请参阅针对特定客户端的说明，了解如何通过 OAuth 设置 Atlas 远程 MCP 服务。或者，你也可以使用 mongodb-atlas-mcp-remote 包并提供服务账号凭据进行连接——设置说明请参阅包的 README。

注意： 你无法通过 HTTP 使用静态 API 密钥向远程 MongoDB MCP 服务进行身份验证。你必须：

使用支持 OAuth 流程的客户端。

使用 mongodb-atlas-mcp-remote stdio 服务，并通过静态的 MDB_MCP_API_CLIENT_ID 和 MDB_MCP_API_CLIENT_SECRET 环境变量完成身份验证。

如需使用服务账号凭据连接 mongodb-atlas-mcp-remote stdio 服务，请将其添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "mongodb-atlas-mcp-remote": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mongodb-atlas-mcp-remote@latest"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID",
        "MDB_MCP_API_CLIENT_SECRET": "$SECRET"
      }
    }
  }
}

选项 3：Atlas API 凭据

使用 Atlas API 服务账号凭据。必须遵循 Atlas API Access 部分中的所有步骤。

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

选项 4：使用环境变量和命令行参数运行独立服务

你可以从配置文件中加载环境变量，也可以像下面的示例一样显式设置环境变量，然后通过 npx 运行服务。

# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the server
npx -y mongodb-mcp-server@latest --readOnly

**💡 平台说明：**以上示例使用 Unix/Linux/macOS 语法。Windows 用户请参阅环境变量，了解特定平台的说明。

完整的配置选项列表请参阅配置选项
有关配置 Atlas Service Accounts 凭据，请参阅 Atlas API 访问
MCP 文件中的连接字符串环境变量示例
MCP 文件中的 Atlas API 凭据环境变量示例

选项 5：使用 Docker

你可以在 Docker 容器中运行 MongoDB MCP 服务，这样可以实现隔离，且无需在本地安装 Node.js。

使用环境变量运行

你可以提供 MongoDB 连接字符串或 Atlas API 凭据：

选项 A：不进行配置

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

选项 B：使用 MongoDB 连接字符串

# Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

**💡 平台说明：**以上示例使用 Unix/Linux/macOS 语法。Windows 用户请参阅环境变量，了解特定平台的说明。

选项 C：使用 Atlas API 凭据

# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID \
  -e MDB_MCP_API_CLIENT_SECRET \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

**💡 平台说明：**以上示例使用 Unix/Linux/macOS 语法。Windows 用户请参阅环境变量，了解特定平台的说明。

MCP 配置文件中的 Docker

不带选项：

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-i",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

使用连接字符串：

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:[email protected]/myDatabase"
      }
    }
  }
}

使用 Atlas API 凭据：

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-e",
        "MDB_MCP_API_CLIENT_ID",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

HTTP 兼容性

对于自定义 HTTP 客户端和宿主，请参阅库指南中的 HTTP 兼容性要求，其中包括协议标头、重定向、旧版会话和请求大小限制。

🛠️ 支持的工具

工具列表

MongoDB 数据库工具

aggregate - 对 MongoDB 集合运行聚合
aggregate-db - 对 MongoDB 数据库运行聚合
collection-indexes - 描述集合的索引
collection-schema - 描述集合的架构
collection-storage-size - 获取集合的大小
connect - 连接到 MongoDB 实例
count - 使用 db.collection.count() 获取 MongoDB 集合中的文档数量，并将 query 作为可选筛选参数
create-collection - 在数据库中创建新集合。如果数据库不存在，则会自动创建。
create-index - 为集合创建索引
db-stats - 返回反映单个数据库使用状态的统计信息
delete-many - 从 MongoDB 集合中删除所有符合筛选条件的文档
disconnect - 关闭 MongoDB 连接并撤销其 connectionId。
drop-collection - 从数据库中删除集合或视图。此方法还会删除与被删除集合关联的所有索引。
drop-database - 删除指定数据库，并删除关联的数据文件
drop-index - 删除指定数据库和集合的索引。
explain - 返回统计信息，描述查询优化器为已评估的方法选择的胜出计划的执行情况
export - 以指定的 EJSON 格式导出查询或聚合结果。
find - 对 MongoDB 集合运行查找查询
insert-many - 将一组文档插入 MongoDB 集合。如果文档列表超过 com.mongodb/maxRequestPayloadBytes，请考虑分批插入。
list-collections - 列出指定数据库中的所有集合
list-connections - 列出活跃的 MongoDB 连接及其 connectionId。使用此工具查找之前建立的 connectionId。
list-databases - 列出 MongoDB 连接中的所有数据库
mongodb-logs - 返回最近记录的 mongod 事件
rename-collection - 重命名 MongoDB 数据库中的集合
update-many - 更新集合中所有符合指定筛选条件的文档。如果文档列表超过 com.mongodb/maxRequestPayloadBytes，请考虑分批更新。

MongoDB Atlas 工具

atlas-connect-cluster - 连接到 MongoDB Atlas 集群，并获取可传递给其他 MongoDB 工具的 connectionId。每次调用都会建立新的独立连接；多个连接可以同时处于活动状态。
atlas-create-access-list - 允许 Ip/CIDR 范围访问 MongoDB Atlas 集群。
atlas-create-cluster - 创建 MongoDB Atlas 集群（M10–M80、副本集或单分片）。默认启用计算自动扩缩：最小实例大小设为所选实例大小，最大实例大小设为高两个级别。磁盘自动扩缩始终启用。支持使用客户管理的密钥（CMK）进行静态加密；CMK 提供商必须已在项目中配置有效的静态加密。该工具会立即返回；请使用 atlas-inspect-cluster 工具轮询集群状态，直到集群就绪（状态：IDLE）。集群达到 IDLE 状态前，无法获取连接字符串。
atlas-create-db-user - 创建 MongoDB Atlas 数据库用户
atlas-create-free-cluster - 创建免费的 MongoDB Atlas 集群
atlas-create-project - 创建 MongoDB Atlas 项目
atlas-get-performance-advisor - 获取 MongoDB Atlas 性能顾问的建议，包括以下操作：建议索引、删除索引建议、架构建议，以及最近的慢查询日志样本（最多 50 条）
atlas-get-regions - 列出云提供商支持的 MongoDB Atlas 区域。
atlas-inspect-access-list - 检查可访问 MongoDB Atlas 集群的 Ip/CIDR 范围。
atlas-inspect-cluster - 检查 MongoDB Atlas 集群的元数据
atlas-list-alerts - 列出 MongoDB Atlas 项目触发的警报。这些是 Atlas 发出的警报，而不是用于定义警报的配置。默认列出 OPEN 警报；将 status 设为 TRACKING 或 CLOSED 可查看其他警报。
atlas-list-clusters - 列出 MongoDB Atlas 集群
atlas-list-db-users - 列出 MongoDB Atlas 数据库用户
atlas-list-orgs - 列出 MongoDB Atlas 组织
atlas-list-projects - 列出 MongoDB Atlas 项目。
atlas-load-sample-dataset - 将 MongoDB 示例数据集加载到 Atlas 集群，或检查先前发起的加载任务状态。要开始新的加载，请提供 clusterName——加载会异步运行，响应中包含 jobId 和初始状态。要检查进度，请再次调用此工具并提供 jobId（示例数据集加载通常需要 1–5 分钟）。状态可能为 WORKING、COMPLETED 或 FAILED。
atlas-pause-resume-cluster - 暂停或恢复专用（M10+）MongoDB Atlas 集群。
atlas-streams-build - 创建 Atlas Stream Processing 资源。适用于“设置 Kafka 管道”、“创建工作区”、“添加连接”或“部署处理器”等场景。使用 resource='workspace' 创建新工作区（指定云提供商、区域和层级）。使用 resource='connection' 向现有工作区添加数据源或接收端。使用 resource='processor' 部署带有管道的流处理器。使用 resource='privatelink' 设置专用网络。典型工作流：创建工作区 → 添加连接 → 部署处理器。
atlas-streams-discover - 发现并检查 Atlas Stream Processing 资源。也适用于“为什么我的处理器失败了”、“我有哪些工作区”、“显示处理器统计信息”或“检查处理器运行状况”等场景。使用 'list-workspaces' 查看项目中的所有工作区。使用检查操作查看特定资源的详细信息。使用 'diagnose-processor' 获取综合运行状况报告，包括状态、统计信息、连接运行状况和近期错误。使用 'get-networking' 查看 PrivateLink 和账户详细信息。
atlas-streams-manage - 管理 Atlas Stream Processing 资源：启动/停止处理器、修改管道、更新配置。也适用于“更改管道”、“扩展我的处理器”或“更新我的工作区层级”等场景。常见工作流：action='stop-processor' → action='modify-processor' → action='start-processor'。管理前，使用 atlas-streams-discover 并指定 action 'inspect-processor' 检查状态。
atlas-streams-teardown - 删除 Atlas Stream Processing 资源。也适用于“移除我的工作区”、“断开数据源”、“删除所有处理器”或“清理我的流处理环境”等场景。删除前会执行基本安全检查：汇总处理器和连接的数量，尽可能标出处理器引用的连接，并在尝试删除时处理器仍在运行的情况下显示 API 错误。删除前请使用 atlas-streams-discover 检查资源。
atlas-upgrade-cluster - 升级或扩缩 MongoDB Atlas 集群。可将 Free 和 Flex 集群升级为 Flex 或 M10 Dedicated。Dedicated 集群可扩缩至其他实例大小，也可更新计算自动扩缩设置。扩缩 Dedicated 集群时，必须至少提供 targetTier、computeAutoScaling、minInstanceSize 或 maxInstanceSize 中的一项。升级到 M10 Dedicated 时，计算自动扩缩默认启用：最小实例大小设为所选实例大小，最大实例大小设为高两个级别，除非另行指定。致大模型：如果尚不清楚提供商和区域，请在调用此工具前一次性询问两者。调用此工具前，请使用 atlas-get-regions 解析自然语言位置或不确定的区域代码。注意：只有在configuration部分设置凭据后，才能使用 Atlas 工具。

MongoDB Atlas 本地工具

atlas-local-connect-deployment - 连接到 MongoDB Atlas 本地部署，并获取可传递给其他 MongoDB 工具的 connectionId
atlas-local-create-deployment - 创建 MongoDB Atlas 本地部署。默认镜像为 preview。如果用户未指定镜像标签，请告知他们默认使用 preview，并提供此链接以了解更多信息：https://hub.docker.com/r/mongodb/mongodb-atlas-local
atlas-local-delete-deployment - 删除 MongoDB Atlas 本地部署
atlas-local-list-deployments - 列出 MongoDB Atlas 本地部署

MongoDB 助手工具

list-knowledge-sources - 列出 MongoDB 助手知识库中可用的数据源。可使用此工具浏览可用的数据源，或查找用于 search-knowledge 的搜索筛选参数。
search-knowledge - 在 MongoDB 助手知识库中搜索信息。内容包括官方文档、精选专家指导，以及 MongoDB 提供的其他资源。支持按数据源和版本筛选。

📄 支持的资源

config - 服务配置，由用户通过环境变量或启动参数提供，并对敏感参数进行脱敏处理。可通过 URI config://config 访问此资源。
debug - 用于排查 MongoDB 连接问题的调试信息。记录最近一次连接尝试和错误信息。可通过 URI debug://mongodb 访问此资源。
exported-data - 用于访问通过导出工具导出的数据的资源模板。可通过 URI exported-data://{exportName} 访问此模板，其中 exportName 是导出工具生成的唯一导出名称。

配置

🔒 安全最佳实践： 我们强烈建议对 API 凭据（MDB_MCP_API_CLIENT_ID、MDB_MCP_API_CLIENT_SECRET）和连接字符串（MDB_MCP_CONNECTION_STRING）等敏感配置使用环境变量，而不是命令行参数。环境变量不会显示在进程列表中，能更好地保护敏感数据。

MongoDB MCP 服务可通过多种方式配置，优先级如下（从高到低）：

命令行参数
环境变量
配置文件

配置选项

环境变量 / CLI 选项	默认值	说明
`MDB_MCP_AGGREGATION_COUNT_MAX_TIME_MS_CAP` / `--aggregationCountMaxTimeMsCap`	`<not set>`	已弃用。请改用 `aggregationCountTimeoutMs`。
`MDB_MCP_AGGREGATION_COUNT_TIMEOUT_MS` / `--aggregationCountTimeoutMs`	`60000`	聚合操作计数阶段的最长时间（毫秒）。用于限制判断结果是否被截断时统计文档所花费的时间。
`MDB_MCP_ALLOW_REQUEST_OVERRIDES` / `--allowRequestOverrides`	`false`	设为 true 时，允许通过请求标头和查询参数覆盖配置值。
`MDB_MCP_API_CLIENT_ID` / `--apiClientId`	`<not set>`	用于身份验证的 Atlas API 客户端 ID。运行 Atlas 工具时必需。
`MDB_MCP_API_CLIENT_SECRET` / `--apiClientSecret`	`<not set>`	用于身份验证的 Atlas API 客户端密钥。运行 Atlas 工具时必需。
`MDB_MCP_ASSISTANT_BASE_URL` / `--assistantBaseUrl`	`"https://knowledge.mongodb.com/api/v1/"`	MongoDB Assistant API 的基本 URL。
`MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` / `--atlasTemporaryDatabaseUserLifetimeMs`	`14400000`	连接到 MongoDB Atlas 集群时创建的临时数据库用户在自动删除前保持有效的时长（毫秒）。
`MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` / `--confirmationRequiredTools`	`"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index,atlas-streams-manage,atlas-streams-teardown"`	执行前需要用户确认的工具名称，以逗号分隔。要求客户端支持征询。
`MDB_MCP_CONNECTION_IDLE_TIMEOUT_MS` / `--connectionIdleTimeoutMs`	`600000`	MongoDB 连接在未使用（没有工具调用访问该连接）时可保持空闲的毫秒数，超过后将关闭连接，以释放底层连接池及其服务端状态。此设置适用于每个连接，与连接作用域无关；预配置连接除外。清理器按此间隔运行。设为 0 可禁用清理；不能为负数。
`MDB_MCP_CONNECTION_SCOPE` / `--connectionScope`	`"session"`	运行时创建的 MongoDB 连接的可见范围。设为 'session'（默认值）时，每个 MCP 会话只能看到自己创建的连接（以及共享的 'preconfigured' 连接），并且会话结束时这些连接会关闭。设为 'global' 时，所有会话共享连接，且连接在会话轮换后仍然保留。已弃用：MCP 协议正转向无会话模式，因此此选项即将移除，连接范围将默认为 'global'。对于共享服务用例，请使用 Atlas-Managed MCP 服务，或使用 @mongodb-js/mcp-cli 包构建经过身份验证的库。注意：在无会话（2026-07-28）HTTP 路径上，没有 mcp-session-id 的请求会回退到共享的 ('global') 范围，因此连接仍可在多个请求间持久保留；旧版有会话路径始终带有由服务端发放的会话。
`MDB_MCP_CONNECTION_STRING` / `--connectionString`	`<not set>`	用于直接连接数据库的 MongoDB 连接字符串。可选；如果未设置，你需要先调用 connect 工具，才能与 MongoDB 数据交互。
`MDB_MCP_DANGEROUS_HOST_BINDING` / `--dangerousHostBinding`	`false`	设为 true 时，允许将 HTTP 服务（及监控服务）绑定到非环回主机，例如 0.0.0.0、局域网 IP 或空主机（所有接口）。绑定到非环回主机会使服务暴露于整个网络，并可能导致未授权访问。默认关闭：除非此项设为 true，否则服务拒绝在非环回主机上启动。
`MDB_MCP_DISABLE_SERVER_SIDE_JS` / `--disableServerSideJs`	`true`	设为 true 时，禁止在查询筛选器和聚合管道中使用服务端 JavaScript 运算符（如 $where、$function 和 $accumulator）。
`MDB_MCP_DISABLE_UNTRUSTED_DATA_WARNING` / `--disableUntrustedDataWarning`	`false`	设为 true 时，工具响应会原样包含可能不可信的数据（如文档或查询结果），不会用分隔符将其括起，也不会添加提示词注入警告。
`MDB_MCP_DISABLED_TOOLS` / `--disabledTools`	`""`	要禁用的工具名称、操作类型和／或工具类别，以逗号分隔。
`MDB_MCP_DRY_RUN` / `--dryRun`	`false`	设为 true 时，以试运行模式运行服务：输出配置和已启用的工具，然后退出，不启动服务。
`MDB_MCP_ELICITATION_TIMEOUT_MS` / `--elicitationTimeoutMs`	`300000`	用户响应征询请求（例如工具确认提示词）的时限（毫秒），超时后请求将失败。
`MDB_MCP_EVICTION_IDLE_GRACE_M_S` / `--evictionIdleGraceMS`	`120000`	当 HTTP 传输达到 maxSessions 上限时，会话在符合最近最少使用淘汰条件前必须保持空闲的时长（仅在传输为 'http' 时使用）。若此值大于 idleTimeoutMs，则会被缩减至 idleTimeoutMs。
`MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` / `--exportCleanupIntervalMs`	`120000`	清理过期导出文件的各次清理周期之间的间隔（毫秒）。
`MDB_MCP_EXPORT_TIMEOUT_MS` / `--exportTimeoutMs`	`300000`	导出内容被视为过期并可供清理之前的时长（毫秒）。
`MDB_MCP_EXPORTS_PATH` / `--exportsPath`	see below*	存储导出数据文件的文件夹。
`MDB_MCP_EXTERNALLY_MANAGED_SESSIONS` / `--externallyManagedSessions`	`false`	设为 true 时，2025 年版本的 HTTP 传输会接受通过 'mcp-session-id' 标头从外部提供的会话 ID。提供外部 ID 后，初始化请求为可选；隐式重新初始化的会话会从会话存储中恢复客户端先前协商的能力。
`MDB_MCP_HEALTH_CHECK_HOST` / `--healthCheckHost`	`<not set>`	已弃用。请改用 `monitoringServerHost`。健康检查 HTTP 服务绑定的主机地址（仅在传输为 'http' 时使用）。如果设置，必须同时设置 `healthCheckPort`。
`MDB_MCP_HEALTH_CHECK_PORT` / `--healthCheckPort`	`<not set>`	已弃用。请改用 `monitoringServerPort`。健康检查 HTTP 服务的端口号（仅在传输为 'http' 时使用）。如果设置，必须同时设置 `healthCheckHost`。
`MDB_MCP_HTTP_BODY_LIMIT` / `--httpBodyLimit`	`102400`	HTTP 请求正文的最大字节数（仅在传输为 'http' 时使用）。此值作为可选的 limit 参数传递给 Express.js 的 json() 中间件。
`MDB_MCP_HTTP_HEADERS` / `--httpHeaders`	`"{}"`	HTTP 服务发起请求时会验证的标头（仅在传输为 'http' 时使用）。
`MDB_MCP_HTTP_HOST` / `--httpHost`	`"127.0.0.1"`	HTTP 服务绑定的主机地址（仅在传输为 'http' 时使用）。
`MDB_MCP_HTTP_PORT` / `--httpPort`	`3000`	HTTP 服务的端口号（仅在传输为 'http' 时使用）。使用 0 表示随机端口。
`MDB_MCP_HTTP_RESPONSE_TYPE` / `--httpResponseType`	`"sse"`	工具响应的 HTTP 响应类型：'sse' 表示服务器发送事件，'json' 表示标准 JSON 响应。
`MDB_MCP_IDLE_TIMEOUT_MS` / `--idleTimeoutMs`	`600000`	客户端断开连接的空闲超时时间（仅适用于 http 传输）。
`MDB_MCP_INDEX_CHECK` / `--indexCheck`	`false`	设为 true 时，强制查询操作使用索引，并拒绝执行集合扫描的查询。
`MDB_MCP_LOG_PATH` / `--logPath`	see below*	存储日志的文件夹。
`MDB_MCP_LOGGERS` / `--loggers`	`"disk,mcp"` see below*	日志记录器类型，以逗号分隔。
`MDB_MCP_MAX_ACTIVE_CONNECTIONS` / `--maxActiveConnections`	`10`	单个作用域（默认是 MCP 会话，参见 connectionScope）可保持打开的 MongoDB 连接数上限。超过上限时，该作用域中最近最少使用的连接将被关闭，其 connectionId 将被撤销。预配置连接不计入上限。
`MDB_MCP_MAX_BYTES_PER_QUERY` / `--maxBytesPerQuery`	`16777216`	find 或 aggregate 工具调用返回结果的最大字节数。此值是这些工具中 responseBytesLimit 参数的上限。
`MDB_MCP_MAX_DOCUMENTS_PER_QUERY` / `--maxDocumentsPerQuery`	`100`	find 或 aggregate 工具调用可返回的最大文档数。对于 find 工具，实际限制取此值和工具的 limit 参数中的较小值。
`MDB_MCP_MAX_SESSIONS` / `--maxSessions`	`1000`	HTTP 传输在内存中保留的并发会话数上限（仅在传输为 'http' 时使用）。每个会话都会占用完整的服务实例、传输和计时器，因此应根据部署可用内存选择合适的值；默认值是较为保守的安全保护值，而非推荐的生产环境值。
`MDB_MCP_MAX_TIME_M_S` / `--maxTimeMS`	`<not set>`	已弃用。请改用 `timeoutMs`。MongoDB 服务端允许操作运行的最长时间（毫秒）。
`MDB_MCP_MCP_CLIENT_LOG_LEVEL` / `--mcpClientLogLevel`	`"debug"`	转发到 MCP 客户端的日志消息的最低严重级别。
`MDB_MCP_MONITORING_SERVER_FEATURES` / `--monitoringServerFeatures`	`"health-check"`	在监控服务上公开的功能（仅在传输为 'http' 且设置了 monitoringServerHost/monitoringServerPort 时使用）。
`MDB_MCP_MONITORING_SERVER_HOST` / `--monitoringServerHost`	`<not set>`	监控 HTTP 服务绑定的主机地址（仅在传输为 'http' 时使用）。如果设置，必须同时设置 `monitoringServerPort`。
`MDB_MCP_MONITORING_SERVER_PORT` / `--monitoringServerPort`	`<not set>`	监控 HTTP 服务的端口号（仅在传输为 'http' 时使用）。如果设置，必须同时设置 `monitoringServerHost`。
`MDB_MCP_NOTIFICATION_TIMEOUT_MS` / `--notificationTimeoutMs`	`540000`	客户端获知断开连接的通知超时时间（仅适用于 http 传输）。
`MDB_MCP_PREVIEW_FEATURES` / `--previewFeatures`	`""`	已启用的预览功能，以逗号分隔。
`MDB_MCP_QUERY_COUNT_MAX_TIME_MS_CAP` / `--queryCountMaxTimeMsCap`	`<not set>`	已弃用。请改用 `queryCountTimeoutMs`。
`MDB_MCP_QUERY_COUNT_TIMEOUT_MS` / `--queryCountTimeoutMs`	`10000`	find 操作计数阶段的最长时间（毫秒）。用于限制判断结果是否被截断时统计文档所花费的时间。
`MDB_MCP_READ_ONLY` / `--readOnly`	`false`	设为 true 时，仅允许读取、连接和元数据操作类型，并禁用创建、更新和删除操作。
`MDB_MCP_TELEMETRY` / `--telemetry`	`"enabled"`	设为 disabled 时，禁用遥测数据收集。
`MDB_MCP_TIMEOUT_MS` / `--timeoutMs`	`<not set>`	MongoDB 操作允许运行的最长时间（毫秒），该值会在每个连接上作为驱动程序的 timeoutMS（客户端操作超时时间，CSOT）应用。它限制整个操作的时长，包括服务器选择和网络往返。
`MDB_MCP_TRANSPORT` / `--transport`	`"stdio"`	可设为 'stdio' 或 'http'。
`MDB_MCP_VOYAGE_API_KEY` / `--voyageApiKey`	`""`	Voyage AI 嵌入服务的 API 密钥（创建具备自动嵌入向量搜索功能的 Atlas Local 部署时必需）。

日志记录器选项

loggers 配置选项用于控制日志的发送位置。你可以指定一个或多个日志记录器类型，并以逗号分隔。可用选项如下：

mcp：将日志发送到 MCP 客户端（如果客户端／传输支持）。
disk：将日志写入磁盘文件。日志文件存储在日志路径中（参见上文的 logPath）。
stderr：将日志输出到标准错误（stderr），适用于调试或在容器中运行。

默认值： disk,mcp（日志会写入磁盘并发送到 MCP 客户端）。

你可以组合多个日志记录器，例如 --loggers disk stderr 或 export MDB_MCP_LOGGERS="mcp,stderr"。

示例：通过环境变量设置日志记录器

export MDB_MCP_LOGGERS="disk,stderr"

💡 平台说明： Windows 用户请参阅环境变量，了解特定于平台的说明。

示例：通过命令行参数设置日志记录器

npx -y mongodb-mcp-server@latest --loggers mcp stderr

日志文件位置

使用 disk 日志记录器时，日志文件存储在：

Windows： %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs
macOS/Linux： ~/.mongodb/mongodb-mcp/.app-logs

你可以通过 logPath 选项更改日志目录。

🔒 安全指南： 运行 MCP 服务的用户账号必须对 logPath 目录同时具有读写权限。请确保使用适当的文件系统权限保护此目录，以防止未经授权访问日志文件。

禁用工具

你可以使用 disabledTools 选项禁用特定工具或工具类别。此选项接受字符串数组，每个字符串可以是工具名称、操作类型或类别。

数组的构造方式取决于你使用的配置方法：

对于环境变量配置，请使用逗号分隔的字符串：export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema"。
对于命令行参数配置，请使用空格分隔的字符串：--disabledTools create update delete atlas collectionSchema。

工具类别：

atlas - MongoDB Atlas 工具，例如列出集群、创建集群等。
mongodb - MongoDB 数据库工具，例如 find、aggregate 等。

操作类型：

create - 创建资源的工具，例如创建集群、插入文档等。
update - 更新资源的工具，例如更新文档、重命名集合等。
delete - 删除资源的工具，例如删除文档、删除集合等。
read - 读取资源的工具，例如 find、aggregate、列出集群等。
metadata - 读取元数据的工具，例如列出数据库／集合／索引、推断集合架构等。
connect - 允许你连接到 MongoDB 实例或切换连接的工具。如果禁用此项，你需要在启动服务时通过配置提供连接字符串。

需要确认

如果你的客户端支持 elicitation，你可以将 MongoDB MCP 服务设置为在执行某些工具前请求用户确认。

当某个工具被标记为需要确认时，服务会向客户端发送 elicitation 请求。支持 elicitation 的客户端随后会提示用户确认，并将响应发回服务。如果客户端不支持 elicitation，该工具将不经确认直接执行。

你可以设置 confirmationRequiredTools 配置选项，指定需要确认的工具名称。默认情况下，以下工具启用了此设置：drop-database、drop-collection、delete-many、drop-index、atlas-create-db-user、atlas-create-access-list、atlas-streams-manage、atlas-streams-teardown。

此外，无论 aggregate 和 aggregate-db 工具是否出现在 confirmationRequiredTools 中，只要其管道包含 $out 或 $merge 阶段，执行前始终会请求确认。这些阶段会向集合写入数据；$out 会完全替换集合内容，因此确认提示会说明受影响的集合以及将对其执行的操作。不含写入阶段的管道不会请求确认。

将任一工具添加到 confirmationRequiredTools 会扩大确认范围：每次调用都会提前显示标准工具级确认提示，写入阶段不会再触发第二次提示。

只读模式

readOnly 配置选项允许你将 MCP 服务限制为仅使用操作类型为“read”、“connect”和“metadata”的工具。启用后，操作类型为“create”、“update”或“delete”的所有工具都不会在服务中注册。

如果你想提供 MongoDB 数据访问权限以供分析，同时不允许对数据或基础设施进行任何修改，此功能会很有用。

你可以通过以下方式启用只读模式：

环境变量：export MDB_MCP_READ_ONLY=true
命令行参数：--readOnly

💡 平台说明： Windows 用户请参阅环境变量，了解适用于该平台的说明。

只读模式启用时，你会在服务日志中看到一条消息，指出哪些工具因这项限制而未能注册。

索引检查模式

indexCheck 配置选项允许你强制要求查询操作使用索引。启用后，如果查询需要扫描集合，就会被拒绝，以确保更好的性能。

如果你想确保数据库查询经过优化，此功能会很有用。

你可以通过以下方式启用索引检查模式：

环境变量：export MDB_MCP_INDEX_CHECK=true
命令行参数：--indexCheck

💡 平台说明： Windows 用户请参阅环境变量，了解适用于该平台的说明。

索引检查模式启用时，如果某个查询因未使用索引而被拒绝，你会看到一条错误消息。

导出

export 工具导出的数据会暂时存储在运行 MCP 服务的机器上配置的 exportsPath 中，直到导出清理进程将其清除。如果未提供 exportsPath 配置，则使用以下默认路径：

Windows： %LOCALAPPDATA%\mongodb\mongodb-mcp\exports
macOS/Linux： ~/.mongodb/mongodb-mcp/exports

exportTimeoutMs 配置用于控制导出数据在多久后被视为已过期并可供清理。默认情况下，导出数据会在 5 分钟（300000ms）后过期。

exportCleanupIntervalMs 配置用于控制清理进程移除过期导出文件的运行频率。默认情况下，清理进程每 2 分钟（120000ms）运行一次。

🔒 安全指南： 运行 MCP 服务的用户帐户必须对 exportsPath 目录同时拥有读取和写入权限。请确保使用适当的文件系统权限保护此目录，防止未经授权访问导出的数据文件，因为这些文件可能包含敏感的 MongoDB 数据。选择导出位置时，请考虑数据的敏感性，并相应地设置严格的权限。

遥测

telemetry 配置选项允许你停用遥测数据收集。启用后，MCP 服务会收集使用数据并将其发送给 MongoDB。

你可以通过以下方式停用遥测：

环境变量：export MDB_MCP_TELEMETRY=disabled
命令行参数：--telemetry disabled
DO_NOT_TRACK 环境变量：export DO_NOT_TRACK=1

💡 平台说明： Windows 用户请参阅环境变量，了解特定于平台的说明。

选择启用预览功能

MongoDB MCP Server 可能会提供仍在开发中的功能，这些功能在后续版本中可能会发生变化。这些功能称为“预览功能”，默认情况下不会启用。通常，这些功能都经过了充分测试，但可能尚未包含我们计划在正式发布版本中提供的全部功能；或者我们希望在这些功能全面开放前收集反馈。要启用一个或多个预览功能，请使用 previewFeatures 配置选项。

对于环境变量配置，请使用逗号分隔的字符串：export MDB_MCP_PREVIEW_FEATURES="feature1,feature2"。
对于命令行参数配置，请使用空格分隔的字符串：--previewFeatures feature1 feature2。

可用预览功能列表：

mcpUI - 启用用于与 MCP 服务交互的可选 Web 界面。

监控服务（健康检查和指标）

使用 --transport http 运行时，你可以启用独立的监控 HTTP 服务，用于健康检查和指标。只有在同时设置了 monitoringServerHost 和 monitoringServerPort 时，才会启动此服务。它会监听独立的主机和端口（与主服务的 httpHost / httpPort 相互独立）。

通过 monitoringServerFeatures 控制公开的功能（默认值：health-check）。可用功能及其端点如下：

功能	端点	说明
`health-check`	`/health`	返回包含服务状态的 JSON 响应，状态码为 `200 OK`。适用于存活探针。
`metrics`	`/metrics`	以 Prometheus 文本格式返回服务指标。

/health 响应会附带 Cache-Control: no-store，其结构如下（只要进程仍在运行，status 始终为 "ok"）：

{
  "status": "ok",
  "version": "1.13.0",
  "uptimeSeconds": 42,
  "timestamp": "2026-06-20T12:00:00.000Z"
}

示例：启用监控服务并调用健康检查端点：

npx -y mongodb-mcp-server@latest --transport http --httpHost 0.0.0.0 --httpPort 3000 --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 &
curl http://0.0.0.0:8080/health
# => {"status":"ok","version":"1.13.0","uptimeSeconds":42,"timestamp":"2026-06-20T12:00:00.000Z"}

如需公开两个端点，请显式传入这些功能：

npx -y mongodb-mcp-server@latest --transport http --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 --monitoringServerFeatures health-check,metrics

💡 注意： healthCheckHost / healthCheckPort 是 monitoringServerHost / monitoringServerPort 的弃用别名，仍会提供相同的 /health 端点。

Atlas API 访问

要使用 Atlas API 工具，你需要在 MongoDB Atlas 中创建服务账户：

ℹ️ 注意： 有关每项 Atlas 操作所需最低权限的详细说明，请参阅下方的 Atlas API 权限部分。

创建服务账户：
- 登录 cloud.mongodb.com 上的 MongoDB Atlas
- 前往 Access Manager > Organization Access
- 点击 Add New > Applications > Service Accounts
- 输入服务账户的名称、说明和有效期（例如，“MCP，MCP Server Access，7 天”）
- 仅分配满足使用场景所需的最低权限。
  - 详情请参阅 Atlas API 权限。
- 点击“Create”

如需了解服务账户的更多信息，请查阅 MongoDB Atlas 文档。

保存客户端凭据：
- 创建后，系统会显示 Client ID 和 Client Secret
- 重要： 请立即复制并保存 Client Secret，因为它之后不会再次显示
添加访问列表条目：
- 将你的 IP 地址添加到 API 访问列表
配置 MCP 服务：
- 使用下方任一配置方法设置 apiClientId 和 apiClientSecret

Atlas API 权限

安全警告： 授予 Organization Owner 角色通常没有必要，且可能带来安全风险。仅分配满足使用场景所需的最低权限。

快速参考：各项操作所需角色

你想执行的操作	最安全的角色（适用范围）
列出组织／项目	组织成员或组织只读（组织）
创建新项目	组织项目创建者（组织）
查看项目中的集群／数据库	项目只读（项目）
创建／管理项目中的集群	项目集群管理员（项目）
管理项目访问列表	项目 IP 访问列表管理员（项目）
管理数据库用户	项目数据库访问管理员（项目）
管理流处理资源	项目流处理所有者（项目）

大多数操作优先使用项目级角色。仅为需要管理或查看的特定项目分配角色。
除非需要对组织中的所有项目和设置进行全面管理，否则请避免使用组织所有者角色。

如需查看角色及其权限的完整列表，请参阅 Atlas 用户角色文档。

配置方式

配置文件

将配置存储在 JSON 文件中，并通过 MDB_MCP_CONFIG 环境变量加载。

🔒 安全最佳实践： 对于敏感字段，优先通过 MDB_MCP_CONFIG 环境变量进行设置，而不是使用配置文件或 --config CLI 参数。命令行参数会显示在进程列表中。

🔒 文件安全： 确保配置文件的所有权和权限设置正确，并限制为运行 MongoDB MCP 服务的用户可访问：

Linux/macOS：
chmod 600 /path/to/config.json
chown your-username /path/to/config.json
Windows： 右键单击文件 → 属性 → 安全 → 将访问权限限制为仅你的用户帐户。

创建包含配置的 JSON 文件（所有键均使用 camelCase）：

{
  "connectionString": "mongodb://localhost:27017",
  "readOnly": true,
  "loggers": ["stderr", "mcp"],
  "apiClientId": "your-atlas-service-accounts-client-id",
  "apiClientSecret": "your-atlas-service-accounts-client-secret",
  "maxDocumentsPerQuery": 100
}

Linux/macOS（bash/zsh）：

export MDB_MCP_CONFIG="/path/to/config.json"
npx -y mongodb-mcp-server@latest

Windows 命令提示符（cmd）：

set "MDB_MCP_CONFIG=C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Windows PowerShell：

$env:MDB_MCP_CONFIG="C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

环境变量

设置环境变量：使用前缀 MDB_MCP_，后接大写并以下划线分隔的选项名称：

Linux/macOS（bash/zsh）：

# Set Atlas API credentials (via Service Accounts)
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"

# Set log path
export MDB_MCP_LOG_PATH="/path/to/logs"

Windows 命令提示符（cmd）：

set "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id"
set "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret"

set "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:[email protected]/myDatabase"

set "MDB_MCP_LOG_PATH=C:\path\to\logs"

Windows PowerShell：

# Set Atlas API credentials (via Service Accounts)
$env:MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
$env:MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"

# Set log path
$env:MDB_MCP_LOG_PATH="C:\path\to\logs"

MCP 配置文件示例

使用环境变量设置连接字符串

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:[email protected]/myDatabase"
      }
    }
  }
}

使用环境变量设置 Atlas API 凭据

{
  "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"
      }
    }
  }
}

命令行参数

启动服务时，将配置选项作为命令行参数传入：

🔒 安全提示： 对于 API 凭据和连接字符串等敏感配置，请使用环境变量，而不要使用命令行参数。

# Set sensitive data as environment variable
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"

# Start the server with command line arguments
npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck

💡 平台提示： 上述示例使用 Unix/Linux/macOS 语法。Windows 用户请参阅环境变量，了解特定平台的说明。

MCP 配置文件示例

使用命令行参数设置连接字符串

🔒 安全提示： 我们不建议将连接字符串作为命令行参数传入。连接字符串可能包含凭据，这些凭据会显示在进程列表中，也可能记录在系统的各个位置，从而导致凭据泄露。建议改为通过环境变量配置连接字符串

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "mongodb+srv://username:[email protected]/myDatabase",
        "--readOnly"
      ]
    }
  }
}

使用命令行参数设置 Atlas API 凭据

🔒 安全提示： 我们不建议将 Atlas API 凭据作为命令行参数传入。提供的凭据会显示在进程列表中，也可能记录在系统的各个位置，从而导致凭据泄露。建议改为通过环境变量配置 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"
      ]
    }
  }
}

代理支持

MCP 服务会检测标准代理环境变量，并将其用于受支持的出站连接，包括 Atlas 管理 API、MongoDB 集群连接、OIDC 身份提供商和 MongoDB Assistant。其行为与 mongosh 一致（两者都依赖 @mongodb-js/devtools-proxy-support），因此，任何适用于 mongosh 的代理配置也适用于此处。

环境变量

启动服务前，请设置相关变量。系统会读取常用的 *_PROXY 变量：

变量	用途
`HTTPS_PROXY`	用于 HTTPS 请求的代理（Atlas API、OIDC、Assistant）
`HTTP_PROXY`	用于普通 HTTP 请求的代理
`ALL_PROXY`	用于所有协议的备用代理
`NO_PROXY`	以逗号分隔的不使用代理的主机／域名列表

# Route outbound traffic through a corporate proxy, except internal hosts
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.internal.example.com"

连接字符串中的代理

对于 MongoDB 集群连接，你可以直接在连接字符串中配置 SOCKS5 代理，而不是使用环境变量：

mongodb+srv://<host>/?proxyHost=127.0.0.1&proxyPort=1080&proxyUsername=user&proxyPassword=pass

支持的参数：proxyHost、proxyPort、proxyUsername、proxyPassword。

证书颁发机构

对于由 @mongodb-js/devtools-proxy-support 处理的 HTTP(S) 请求（Atlas API、OIDC 和 MongoDB Assistant），除捆绑的 CA 外，还会信任操作系统的证书存储——与 mongosh 的处理方式相同。因此，安装在操作系统级别的企业根证书会自动生效。

🚀在公有云上部署

你可以使用 deploy/ 下的部署资源，将 MongoDB MCP Server 部署到首选的云服务提供商。每份指南都介绍了先决条件、配置和可简化部署流程的自动化脚本。

Azure

如需详细的 Azure 说明，请参阅 deploy/azure/README.md。

部署限制

CLI 工具（mongodb-mcp-server / npx mongodb-mcp-server）专为单用户、本地主机（或私有）部署而设计，操作用户是唯一主体。它不内置身份验证，且 MCP 协议不会传递经过验证的终端用户身份。它不适合为多个用户提供服务——前面没有身份验证中间件来区分调用方或控制连接隔离。

因此，如果你将其暴露到网络中，或将其作为共享服务运行，就必须负责确保隔离：

**暴露到互联网：**在没有身份验证的情况下绑定到 0.0.0.0 / ::（或任何非环回主机），会暴露一个未经身份验证的端点，该端点可通过已配置的连接字符串执行 MongoDB 操作（包括破坏性操作）。如果你有意绑定到非环回主机，必须设置 MDB_MCP_DANGEROUS_HOST_BINDING=true（参见配置选项）。
**多用户隔离：**连接由（即将移除的）connectionScope 选项限定范围，其默认值将改为 global——每个请求都会共享同一范围。在无会话路径上用于标识范围的 mcp-session-id 标头由客户端自行声明，并非安全边界；不带此标头的请求也会落入共享范围。因此，多个用户可能会看到并操作彼此的连接，包括任何 Atlas 临时数据库用户凭据。服务不会区分调用方。要确保适当的隔离，你可以设置一个经过身份验证的中间件来控制 mcp-session-id 标头，或者使用 @mongodb-js/mcp-* 库包提供自定义范围机制。

请勿在未于前端添加自有身份验证和身份识别层的情况下，将 CLI 工具作为面向互联网的共享端点运行。

使用库并添加自己的身份验证

对于多租户或公开部署，请改用 @mongodb-js/mcp-* 库构建经过身份验证的解决方案：

在自己的代理或中间件处终止身份验证／用户身份验证，并通过 authInfo 将经过验证的主体传入请求（SDK 的 createMcpHandler 和旧版处理程序都会转发它）。
提供一个 connectionScope 策略，以经过验证的最终用户身份（例如 OIDC sub 声明）作为键，从而隔离每位用户的连接和凭据——对于多用户流量，请勿让它回退到共享的 global 作用域。

已经在使用 MongoDB Atlas？ 对于多租户 Atlas 集群使用场景，最简单的替代方案是 MongoDB Atlas-Managed MCP 服务——这是一个托管且经过身份验证的部署，会为你处理每位用户的身份（OAuth／服务账户），无需你自行搭建。请参阅上文中的选项 2。

请参阅 MCP_SERVER_LIBRARY.md，了解嵌入 API、createHttpTransportRunnerFromConfig／CliMcpHttpServer、connectionScope 策略接入点，以及可直接参考的按用户隔离示例。

🤝贡献

有兴趣参与贡献？太好了！请查看我们的贡献指南，了解代码贡献规范、标准、添加新工具的方式以及故障排查信息。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

atlas-mcp-server

关于 atlas-mcp-server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

MongoDB MCP 服务

快速开始

使用 MongoDB 官方 AI Agent 插件

使用设置脚本

使用 MongoDB MCP Server 设置技能

使用手动配置

📚 目录

前置条件

手动设置

选项 1：连接字符串

选项 2：连接到 MongoDB Atlas 托管的 MCP 服务

选项 3：Atlas API 凭据

选项 4：使用环境变量和命令行参数运行独立服务

选项 5：使用 Docker

使用环境变量运行

选项 A：不进行配置

选项 B：使用 MongoDB 连接字符串

选项 C：使用 Atlas API 凭据

MCP 配置文件中的 Docker

HTTP 兼容性

🛠️ 支持的工具

工具列表

MongoDB 数据库工具

MongoDB Atlas 工具

MongoDB Atlas 本地工具

MongoDB 助手工具

📄 支持的资源

配置

配置选项

日志记录器选项

示例：通过环境变量设置日志记录器

示例：通过命令行参数设置日志记录器

日志文件位置

禁用工具

需要确认

只读模式

索引检查模式

导出

遥测

选择启用预览功能

监控服务（健康检查和指标）

Atlas API 访问

Atlas API 权限

快速参考：各项操作所需角色

配置方式

配置文件

环境变量

MCP 配置文件示例

使用环境变量设置连接字符串

使用环境变量设置 Atlas API 凭据

命令行参数

MCP 配置文件示例

使用命令行参数设置连接字符串

使用命令行参数设置 Atlas API 凭据

代理支持

环境变量

连接字符串中的代理

证书颁发机构

🚀在公有云上部署

Azure

部署限制

使用库并添加自己的身份验证

🤝贡献

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？