MongoDB MCP Server 进行故障排除

身份验证要求

必需： Atlas API凭证•
apiClientId（服务帐户ID）
•apiClientSecret （服务帐户密钥）

必须: Docker 运行时
• 无需其他凭证
• 自动托管本地部署

可选：多种连接方法
•
预配置的连接字符串• 的Atlas凭证• 通过atlas-connect-cluster
工具进行运行时连接connect
• 通过 进行本地部署atlas-local-connect-deployment

连接方法

基于API连接到Atlas Management API
• 无需直接数据库连接
• 使用Atlas REST API端点

本地部署管理
• 使用 Docker 容器
• 无需外部网络访问

直接连接到MongoDB数据库。可用的多个选项：
• 配置的连接字符串
• 运行时连接提示
• Atlas 集群发现
• 本地部署连接

权限要求

服务账户角色（Atlas 项目级别）：
• Project Read Only（读取操作的最小值）
• Project Owner（用于集群创建/管理）
• Organization Owner（用于项目创建）

系统要求：
• Docker运行时权限
•
本地文件系统访问权限• 容器管理功能

数据库用户角色（如果适用）：
•readAnyDatabase （只读模式）
•readWriteAnyDatabase （完整操作）
• 特定数据库/集合的自定义角色

配置选项

环境变量:
MDB_MCP_API_CLIENT_ID 或
MDB_MCP_API_CLIENT_SECRET

命令行:
• --apiClientId
• --apiClientSecret

环境变量:
• DOCKER_HOST (可选)

命令行:
• 无需特定 MCP 配置
• 自动检测 Docker 运行时

环境变量（可选）：
MDB_MCP_CONNECTION_STRING

命令行（可选）：
• 作为位置参数的连接字符串：
--connectionString

运行时方法：
• 通过 LLM 提示符进行交互式连接
• Atlas基于档案的发现

只读模式影响

• 读取操作： ✅ 可用
• 集群检查： ✅ 可用
• 集群创建： ❌ 已禁用
• 用户管理： ❌ 已禁用

• 本地部署创建： ✅ 可用
• 部署检查： ✅ 可用
• 容器管理： ✅ 可用
• 无只读限制

• 读取操作：✅ 可用
• 查询操作：✅ 可用
• 聚合：✅ 可用，前提是没有 $out 或 $merge 阶段。
• 插入/更新/删除：❌ 禁用
• 索引创建：❌ 禁用

工具类别

可以通过以下方式禁用：
--disabledTools atlas 或
MDB_MCP_DISABLED_TOOLS="atlas"

可以通过以下方式禁用：
--disabledTools atlas 或
MDB_MCP_DISABLED_TOOLS="atlas"

可以通过以下方式禁用：
--disabledTools mongodb 或
MDB_MCP_DISABLED_TOOLS="mongodb"

网络要求

到Atlas API 的出站 HTTPS：
• 标准互联网连接

本地 Docker 网络：
• Docker 守护进程访问
• 本地端口可用性
• 无外部网络要求

连接到 MongoDB 集群（如适用）：
• Atlas：mongodb+srv:// （端口 27017）
• 分片集群（端口 27016）
• 自管理：自定义主机/端口
• 本地部署：Docker 网络
• 按需进行 VPC/网络访问

可用操作

•
组织管理•
项目管理• 集群生命周期（创建、检查、删除）
•数据库用户管理•
访问列表配置
•Performance Advisor建议
• 警报管理

• 本地部署创建和管理
• 容器生命周期操作
• 本地集群配置
• 开发环境设置
• 测试部署管理

• 增删改查操作（查找、插入、更新、删除）•


聚合管道• 索引管理•

集合和数据库管理• 模式检查•
向量搜索操作•
词法搜索操作• 数据导出

Error Scenarios

缺少 API 凭证：
Atlas 工具返回："Atlas API 凭证未配置"

权限不足：
Atlas API 返回 HTTP 403 错误

Docker不可用："Docker 守护进程 not 运行" 或 "Docker not installed"

容器问题：端口冲突、资源限制

连接失败（配置后）：
网络超时、身份验证失败

缺少数据库权限：
MongoDB 授权错误

临时凭证

不适用：
使用持久性服务账户凭证

不适用：本地部署使用容器托管的身份验证

自动生成的数据库用户（如适用）：使用不带连接字符串的Atlas API凭证时：
• 随机用户名/密码
4
•默认为 小时过期 • 自动角色分配