MongoDB MCP Server

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 的说明，请参阅手动设置。

📚 目录

• 🚀 开始使用
  • 前置条件
  • 手动设置
• 🛠️ 支持的工具
  • MongoDB Atlas 工具
  • MongoDB 数据库工具
  • MongoDB 助手工具
• 📄 支持的资源
• ⚙️ 配置
  • 配置选项
  • Atlas API 访问
  • 配置方式
    • 环境变量
    • 命令行参数
    • MCP 客户端配置
    • 代理支持
• 🚀 在公有云上部署
  • Azure Cloud
• 🤝 参与贡献

前置条件

说明

对 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 服务。

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

• Devin AI
• Claude Desktop & Web
• Cursor
• Codex
• 其他 AI 客户端

默认安全提示： 以下所有示例默认包含 --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 服务可通过多种方式配置，优先级如下（从高到低）：

1. 命令行参数
2. 环境变量
3. 配置文件

配置选项

环境变量 / 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 权限部分。

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

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

2. 保存客户端凭据：

   • 创建后，系统会显示 Client ID 和 Client Secret
   • 重要： 请立即复制并保存 Client Secret，因为它之后不会再次显示

3. 添加访问列表条目：

   • 将你的 IP 地址添加到 API 访问列表

4. 配置 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 策略接入点，以及可直接参考的按用户隔离示例。

🤝贡献

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