MongoDB MCP Server

一个用于与 MongoDB 数据库和 MongoDB Atlas 交互的 Model Context Protocol 服务器。

📚 目录

• 🚀 快速开始

  • 先决条件

  • 设置

    • 快速开始

• 🛠️ 支持的工具

  • MongoDB Atlas 工具

  • MongoDB 数据库工具

• ⚙️ 配置

  • 配置选项

  • Atlas API 访问

  • 配置方法

    • 环境变量

    • 命令行参数

    • MCP 客户端配置

• 🤝 贡献

先决条件

• Node.js（v20.10.0 或更高版本）

node -v

• MongoDB 连接字符串或 Atlas API 凭据，除非完成配置，否则服务器将无法启动。

  • 使用 Atlas 工具需要 Service Accounts Atlas API 凭据。您可以在 MongoDB Atlas 中创建服务账户，并使用其凭据进行身份验证。有关更多详情，请参阅 Atlas API 访问。

  • 如果您有 MongoDB 连接字符串，可以直接使用它连接到您的 MongoDB 实例。

设置

快速开始

注意： 使用 Atlas API 凭据时，请务必仅为您的服务账户分配所需的最低权限。有关详情，请参阅 Atlas 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

选项 1：连接字符串参数

您可以通过参数传递连接字符串，请确保使用有效的用户名和密码。

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb://localhost:27017/myDatabase"
      ]
    }
  }
}

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

选项 2：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"
      ]
    }
  }
}

选项 3：使用命令行参数的独立服务

使用 npx 命令启动服务器：

 npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret"

• 有关参数的完整列表，请参阅 配置选项

• 要配置您的 Atlas 服务账户凭据，请参阅 Atlas API 访问

选项 4：使用环境变量的独立服务

 npx -y mongodb-mcp-server

您可以在配置文件中使用环境变量，或设置环境变量后通过 npx 运行服务器。

• 通过 MCP 文件中的环境变量设置连接字符串 示例

• 通过 MCP 文件中的环境变量设置 Atlas API 凭据 示例

选项 5：使用 Docker

您可以在 Docker 容器中运行 MongoDB MCP Server，这样可以提供隔离环境，且无需本地安装 Node.js。

使用环境变量运行

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

选项 A：无配置

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

选项 B：带 MongoDB 连接字符串

docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  mongodb/mongodb-mcp-server:latest

选项 C：带 Atlas API 凭据

docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
  mongodb/mongodb-mcp-server:latest

MCP 配置文件中的 Docker

无选项：

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

带连接字符串：

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

带 Atlas API 凭据：

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

🛠️ 支持的工具

工具列表

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 工具才可用。

MongoDB 数据库工具

• connect - 连接到 MongoDB 实例

• find - 对 MongoDB 集合执行 find 查询

• aggregate - 对 MongoDB 集合执行聚合操作

• count - 获取 MongoDB 集合中的文档数量

• insert-one - 向 MongoDB 集合插入单个文档

• insert-many - 向 MongoDB 集合插入多个文档

• create-index - 为 MongoDB 集合创建索引

• update-one - 更新 MongoDB 集合中的单个文档

• update-many - 更新 MongoDB 集合中的多个文档

• rename-collection - 重命名 MongoDB 集合

• delete-one - 从 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 数据库的统计信息

配置

MongoDB MCP Server 可以使用多种方法进行配置，优先级如下（从高到低）：

1. 命令行参数

2. 环境变量

配置选项

日志路径

默认日志位置如下：

• Windows：%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs

• macOS/Linux：~/.mongodb/mongodb-mcp/.app-logs

禁用的工具

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

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

• 对于环境变量配置，使用逗号分隔的字符串：export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema"。

• 对于命令行参数配置，使用空格分隔的字符串：--disabledTools create update delete atlas collectionSchema。

工具类别：

• atlas - MongoDB Atlas 工具，例如 list clusters、create cluster 等。

• mongodb - MongoDB 数据库工具，例如 find、aggregate 等。

操作类型：

• create - 创建资源的工具，例如 create cluster、insert document 等。

• update - 更新资源的工具，例如 update document、rename collection 等。

• delete - 删除资源的工具，例如 delete document、drop collection 等。

• read - 读取资源的工具，例如 find、aggregate、list clusters 等。

• metadata - 读取元数据的工具，例如 list databases、list collections、collection schema 等。

只读模式

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

这对于以下场景非常有用：你希望提供对 MongoDB 数据的访问以进行分析，但不允许对数据或基础设施进行任何修改。

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

• 环境变量：export MDB_MCP_READ_ONLY=true

• 命令行参数：--readOnly

当只读模式处于活动状态时，你会在服务器日志中看到一条消息，说明哪些工具因该限制而无法注册。

遥测

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

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

• 环境变量：export MDB_MCP_TELEMETRY=disabled

• 命令行参数：--telemetry disabled

• DO_NOT_TRACK 环境变量：export DO_NOT_TRACK=1

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 days"）

   • 仅分配你的用例所需的最低权限。

     • 有关详细信息，请参阅 Atlas API 权限。

   • 单击"Create"

要了解有关服务账户的更多信息，请查看 MongoDB Atlas 文档。

2. 保存客户端凭据：

   • 创建后，系统会显示 Client ID 和 Client Secret

   • 重要提示： 请立即复制并保存 Client Secret，因为它不会再次显示

3. 添加访问列表条目：

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

4. 配置 MCP 服务器：

   • 使用以下配置方法之一来设置你的 apiClientId 和 apiClientSecret

Atlas API 权限

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

快速参考：每个操作所需的角色

• 对于大多数操作，优先使用项目级角色。仅将角色分配给需要管理或查看的特定项目。

• 避免使用 Organization Owner，除非你需要对组织中的所有项目和设置拥有完全的管理控制权。

有关角色及其权限的完整列表，请参阅 Atlas User Roles 文档。

配置方法

环境变量

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

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

export MDB_MCP_LOG_PATH="/path/to/logs"

MCP 配置文件示例

使用环境变量的连接字符串

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/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"
      }
    }
  }
}

命令行参数

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

npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs

MCP 配置文件示例

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

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}

使用命令行参数的 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"
      ]
    }
  }
}

🤝 参与贡献

有兴趣参与贡献吗？太好了！请查看我们的贡献指南，了解代码贡献、标准、添加新工具和故障排除信息的相关指南。