使用说明

MongoDB MCP服务器

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

📚 目录

🚀 入门指南
- 先决条件
- 设置
  - 快速开始
🛠️ 支持的工具
- MongoDB Atlas工具
- MongoDB数据库工具
⚙️ 配置
🤝 贡献

先决条件

Node.js（v20或更高版本）

node -v

MongoDB连接字符串或Atlas API证书， 除非配置，否则服务器将不会启动.
- 服务帐户图集API证书 需要使用Atlas工具。您可以在MongoDB Atlas中创建一个服务帐户，并使用其凭据进行身份验证。看 Atlas API访问了解更多详情。
- 如果你有一个MongoDB连接字符串，你可以直接使用它来连接到你的MongoDB实例。

设置

快速开始

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

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

帆板运动:https://docs.windsurf.com/windsurf/mcp
VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
克劳德桌面: https://modelcontextprotocol.io/quickstart/user
光标: https://docs.cursor.com/context/model-context-protocol

🐳 Docker 部署

我们提供预构建的Docker镜像，可以通过GitHub Actions下载：

下载镜像：

访问 GitHub操作页面
选择最新的构建运行记录
在 "Artifacts" 部分下载 mongodb-mcp-server-{version}-amd64.tar.gz

使用方法：

# 解压并加载镜像
gunzip mongodb-mcp-server-{version}-amd64.tar.gz
docker load -i mongodb-mcp-server-{version}-amd64.tar

# 运行容器
docker run -d -p 8000:8000 \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  -e MDB_DB="myDatabase" \
  mongodb-mcp-server:latest

# 或使用Atlas API凭据
docker run -d -p 8000:8000 \
  -e MDB_MCP_API_CLIENT_ID="your-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-client-secret" \
  mongodb-mcp-server:latest

Docker环境变量：

PORT: 服务端口 (默认: 8000)
MDB_MCP_CONNECTION_STRING: MongoDB连接字符串
MDB_DB: 默认数据库名称 (默认: ChatBI)
MDB_MCP_API_CLIENT_ID: Atlas API客户端ID
MDB_MCP_API_CLIENT_SECRET: Atlas API客户端密钥

选项1：连接字符串参数

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

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

选项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文件中的环境变量连接字符串例子
Atlas API凭证通过MCP文件中的环境变量例子

🛠️ 支持的工具

刀具清单

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数据库用户

注意：只有在上设置凭据时，图集工具才可用配置部分。

MongoDB数据库工具

connect -连接到MongoDB实例
find -对MongoDB集合运行查找查询
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服务器可以使用多种方法进行配置，优先级如下（从高到低）：

命令行参数
环境变量

配置选项

选项	描述
`apiClientId`	用于身份验证的Atlas API客户端ID
`apiClientSecret`	Atlas API客户端认证机密
`connectionString`	用于直接数据库连接的MongoDB连接字符串（可选用户可以选择在每次工具调用时通知它）
`defaultDatabase`	MongoDB操作的默认数据库名称。可以通过以下方式设置 `--database` arg或 `MDB_DB`/`MDB_MCP_DEFAULT_DATABASE` env变量。默认为“ChatBI”
`logPath`	用于存储日志的文件夹
`disabledTools`	一系列将被禁用的工具名称、操作类型和/或工具类别
`readOnly`	当设置为true时，只允许读取和元数据操作类型，禁用创建/更新/删除操作
`telemetry`	当设置为禁用时，禁用遥测收集

日志路径

默认日志位置如下：

窗户： %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工具，如列表集群、创建集群等。
mongodb -MongoDB数据库工具，如查找、聚合等。

操作类型：

create -创建资源的工具，如创建集群、插入文档等。
update -更新资源的工具，如更新文档、重命名集合等。
delete -删除资源的工具，如删除文档、删除收藏等。
read -读取资源的工具，如查找、聚合、列出集群等。
metadata -读取元数据的工具，如列表数据库、列表集合、集合模式等。

只读模式

这 readOnly 配置选项允许您限制MCP服务器仅使用具有“读取”和“元数据”操作类型的工具。启用后，所有具有“创建”、“更新”或“删除”操作类型的工具都不会在服务器上注册。

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

您可以使用以下方式启用只读模式：

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

当只读模式处于活动状态时，您将在服务器日志中看到一条消息，指示哪些工具因此限制而无法注册。

数据库限制

这 defaultDatabase 配置选项允许您限制MCP服务器仅在特定数据库上运行。配置后，默认情况下，所有数据库工具都将使用指定的数据库 list-databases 禁用该工具以防止发现其他数据库。

这对于出于安全或操作原因而限制对特定数据库的访问的场景非常有用。

您可以使用以下命令设置默认数据库：

环境变量: export MDB_DB=ChatBI 或 export MDB_MCP_DEFAULT_DATABASE=ChatBI
命令行参数: --database ChatBI
Docker环境变量: -e MDB_DB=ChatBI

配置默认数据库时：

除非在工具参数中明确重写，否则所有数据库操作都将使用此数据库
这 list-databases 禁用该工具以防止数据库发现
如果需要，用户仍然可以在单个工具调用中指定不同的数据库名称

遥测

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

您可以使用以下方式禁用遥测：

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

Atlas API访问

要使用Atlas API工具，您需要在MongoDB Atlas中创建一个服务帐户：

创建服务帐户：
- 登录MongoDB Atlas cloud.mongodb.com
- 导航到Access Manager>组织访问
- 单击添加新>应用程序>服务帐户
- 输入您的服务帐户的名称、描述和到期时间（例如，“MCP，MCP服务器访问，7天”）
- 选择适当的权限（要获得完全访问权限，请使用“组织所有者”）
- 点击“创建”

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

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

配置方法

环境变量

使用前缀设置环境变量 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"

# Set default database for operations (limits MCP to only use this database)
export MDB_MCP_DEFAULT_DATABASE="ChatBI"
# Or alternatively, use the shorter form:
export MDB_DB="ChatBI"

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" --database="ChatBI" --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"
      ]
    }
  }
}

🤝 贡献

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

使用说明

MongoDB MCP服务器

📚 目录

先决条件

设置

快速开始

🐳 Docker 部署

选项1：连接字符串参数

选项2:Atlas API凭据参数

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

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

🛠️ 支持的工具

刀具清单

MongoDB Atlas工具

MongoDB数据库工具

配置

配置选项

日志路径

禁用工具

只读模式

数据库限制

遥测

Atlas API访问

配置方法

环境变量

MCP配置文件示例

带有环境变量的连接字符串

带有环境变量的Atlas API证书

命令行参数

MCP配置文件示例

带命令行参数的连接字符串

带有命令行参数的Atlas API凭据

🤝 贡献

相关 MCP

MySQL数据库管理工具

MongoDB 数据库 MCP 服务器

PostgreSQL管理服务器

PocketBase 数据库 MCP 服务器

SQLite数据库服务

MySQL数据库操作工具