mongodb-mcp服务器

Name: mongodb-mcp服务器
Author: mongodb-js

作者：mongodb-js826 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

MongoDB MCP 服务器

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

📚 目录

🚀 开始使用
- 先决条件
- 设置
  - 快速开始
🛠️ 支持的工具
- MongoDB Atlas 工具
- MongoDB 数据库工具
📄 支持的资源
⚙️ 配置
🚀 在公共云上部署
- Azure 云
🤝 贡献

先决条件

Node.js
- 至少 20.19.0
- 如果使用 v22，则至少 v22.12.0
- 否则任何版本 23+

node -v

一个 MongoDB 连接字符串或 Atlas API 凭证，除非已配置，否则服务器不会启动。
- 使用 Atlas 工具需要服务账户 Atlas API 凭证。您可以在 MongoDB Atlas 中创建一个服务账户并使用其凭证进行身份验证。有关更多详细信息，请参阅 Atlas API 访问。
- 如果您有 MongoDB 连接字符串，可以直接使用它连接到您的 MongoDB 实例。

设置

快速开始

🔒 安全建议 1: 当使用 Atlas API 凭证时，请确保仅分配给您的服务账户所需的最小权限。详情请参阅 Atlas API 权限。

🔒 安全建议 2: 为了增强安全性，我们强烈建议使用环境变量传递敏感配置，如连接字符串和 API 凭证，而不是命令行参数。命令行参数可能在进程列表和各种系统位置中可见，可能会暴露您的秘密。环境变量提供了一种更安全的方式来处理敏感信息。

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

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

Windsurf: https://docs.windsurf.com/windsurf/mcp
VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Claude Desktop: https://modelcontextprotocol.io/quickstart/user
Cursor: https://docs.cursor.com/context/model-context-protocol

默认安全通知: 下面的所有示例都默认包含 --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: Atlas API 凭证

使用您的 Atlas API 服务账户凭证。必须遵循 Atlas API 访问部分中的所有步骤。

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

选项 3: 使用环境变量和命令行参数的独立服务

您可以从配置文件中定义环境变量，或者像下面的例子一样显式设置它们，并通过 npx 启动服务器。

# 首先设置您的凭据作为环境变量
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# 然后启动服务器
npx -y mongodb-mcp-server@latest --readOnly

💡 平台提示: 上面的示例使用了 Unix/Linux/macOS 语法。对于 Windows 用户，请参阅环境变量获取特定平台的说明。

有关完整的配置选项列表，请参阅配置选项
如需配置您的 Atlas 服务账户凭证，请参阅 Atlas API 访问
MCP 文件中的连接字符串通过环境变量示例
MCP 文件中的 Atlas API 凭证通过环境变量示例

选项 4: 使用 Docker

您可以在 Docker 容器中运行 MongoDB MCP 服务器，这提供了隔离性并且不需要本地 Node.js 安装。

使用环境变量运行

您可以提供 MongoDB 连接字符串或 Atlas API 凭证：

选项 A: 无配置

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

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

# 首先设置您的凭据作为环境变量
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# 然后启动 Docker 容器
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 凭证

# 首先设置您的凭据作为环境变量
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# 然后启动 Docker 容器
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 用户，请参阅环境变量获取特定平台的说明。

Docker 在 MCP 配置文件中

无选项：

{
  "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:password@cluster.mongodb.net/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"
      }
    }
  }
}

选项 5: 作为 HTTP 服务器运行

⚠️ 安全通知: 该服务器现在支持远程连接的流式 HTTP 传输。不推荐在没有实现适当的身份验证和安全措施的情况下在生产环境中使用 HTTP 传输。

建议的安全措施示例:

实现身份验证（例如，API 网关，反向代理）
使用 HTTPS/TLS 加密
部署在防火墙后面或私有网络中
实现速率限制
永远不要直接暴露到互联网

更多详情，请参阅 MCP 安全最佳实践。

您可以将 MongoDB MCP 服务器作为 HTTP 服务器运行，而不是默认的 stdio 传输。如果您想通过 HTTP 与服务器交互，例如从 Web 客户端或在特定端口上公开服务器，这很有用。

要使用 HTTP 传输启动服务器，请使用 --transport http 选项：

npx -y mongodb-mcp-server@latest --transport http

默认情况下，服务器将在 http://127.0.0.1:3000 监听。您可以使用 --httpHost 和 --httpPort 选项自定义主机和端口：

npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort=8080

--httpHost（默认: 127.0.0.1）: 绑定 HTTP 服务器的主机。
--httpPort（默认: 3000）: HTTP 服务器的端口号。

注意: 默认传输是 stdio，适用于与大多数 MCP 客户端集成。如果需要通过 HTTP 与服务器交互，请使用 http 传输。

🛠️ 支持的工具

工具列表

MongoDB Atlas 工具

atlas-list-orgs - 列出 MongoDB Atlas 组织
atlas-list-projects - 列出 MongoDB Atlas 项目
atlas-create-project - 创建新的 MongoDB Atlas 项目
atlas-list-clusters - 列出 MongoDB Atlas 集群
atlas-inspect-cluster - 检查特定的 MongoDB Atlas 集群
atlas-create-free-cluster - 创建免费的 MongoDB Atlas 集群
atlas-connect-cluster - 连接到 MongoDB Atlas 集群
atlas-inspect-access-list - 检查具有访问 MongoDB Atlas 集群权限的 IP/CIDR 范围
atlas-create-access-list - 配置 MongoDB Atlas 集群的 IP/CIDR 访问列表
atlas-list-db-users - 列出 MongoDB Atlas 数据库用户
atlas-create-db-user - 创建 MongoDB Atlas 数据库用户
atlas-list-alerts - 列出 MongoDB Atlas 项目的警报
atlas-get-performance-advisor - 获取 Atlas 性能顾问建议（索引建议、删除索引建议、模式建议、慢查询日志）

注意：只有在配置部分设置了凭证时，才能使用这些工具。

MongoDB Atlas 本地工具

atlas-local-list-deployments - 列出 MongoDB Atlas 本地部署
atlas-local-create-deployment - 创建 MongoDB Atlas 本地部署
atlas-local-connect-deployment - 连接到 MongoDB Atlas 本地部署
atlas-local-delete-deployment - 删除 MongoDB Atlas 本地部署

MongoDB 数据库工具

connect - 连接到 MongoDB 实例
find - 对 MongoDB 集合执行查找查询。返回的文档数量由 limit 参数和服务器的 maxDocumentsPerQuery 配置中的较小值决定。返回文档的总大小也由 responseBytesLimit 参数和服务器的 maxBytesPerQuery 配置中的较小值决定。
aggregate - 对 MongoDB 集合执行聚合操作。返回的文档数量由服务器的 maxDocumentsPerQuery 配置决定。返回文档的总大小也由 responseBytesLimit 参数和服务器的 maxBytesPerQuery 配置中的较小值决定。
count - 获取 MongoDB 集合中的文档数量
insert-many - 将多个文档插入 MongoDB 集合
create-index - 为 MongoDB 集合创建索引
update-many - 更新 MongoDB 集合中的多个文档
rename-collection - 重命名 MongoDB 集合
delete-many - 从 MongoDB 集合中删除多个文档
drop-collection - 从 MongoDB 数据库中删除集合
drop-database - 删除 MongoDB 数据库
list-databases - 列出 MongoDB 连接的所有数据库
list-collections - 列出给定数据库的所有集合
collection-indexes - 描述集合的索引
collection-schema - 描述集合的模式
collection-storage-size - 获取集合的大小（MB）
db-stats - 返回关于 MongoDB 数据库的统计信息
export - 将查询或聚合结果导出为 EJSON 格式。创建一个可通过 exported-data 资源访问的唯一命名导出。

📄 支持的资源

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 选项	环境变量	默认值	描述
`apiClientId`	`MDB_MCP_API_CLIENT_ID`	`<未设置>`	用于身份验证的 Atlas API 客户端 ID。运行 Atlas 工具时需要。
`apiClientSecret`	`MDB_MCP_API_CLIENT_SECRET`	`<未设置>`	用于身份验证的 Atlas API 客户端密钥。运行 Atlas 工具时需要。
`atlasTemporaryDatabaseUserLifetimeMs`	`MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS`	`14400000`	临时数据库用户在连接到 MongoDB Atlas 集群时创建，然后在自动删除之前保持活动状态的时间（毫秒）。
`confirmationRequiredTools`	`MDB_MCP_CONFIRMATION_REQUIRED_TOOLS`	`"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"`	需要在执行前获得用户确认的工具名称，逗号分隔。需要客户端支持提示。
`connectionString`	`MDB_MCP_CONNECTION_STRING`	`<未设置>`	MongoDB 连接字符串，用于直接数据库连接。可选，如果没有设置，您需要调用连接工具才能与 MongoDB 数据交互。
`disableEmbeddingsValidation`	`MDB_MCP_DISABLE_EMBEDDINGS_VALIDATION`	`false`	设置为 true 时禁用嵌入维度的验证。
`disabledTools`	`MDB_MCP_DISABLED_TOOLS`	`""`	工具名称、操作类型和/或工具类别的逗号分隔值，这些工具将被禁用。
`exportCleanupIntervalMs`	`MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS`	`120000`	导出清理周期之间的时间（毫秒），在此期间会删除过期的导出文件。
`exportTimeoutMs`	`MDB_MCP_EXPORT_TIMEOUT_MS`	`300000`	导出被认为过期并符合条件进行清理的时间（毫秒）。
`exportsPath`	`MDB_MCP_EXPORTS_PATH`	见下文*	存储导出数据文件的文件夹。
`httpHost`	`MDB_MCP_HTTP_HOST`	`"127.0.0.