使用此页面上的信息可帮助解决MongoDB MCP 服务器的问题。
日志文件
如果 MCP 服务器出现问题，请检查 MCP 服务器日志以获取有助于解决问题的信息。
默认下，MCP 服务器将日志写入磁盘，并将日志发送到 MCP客户端。您可以更改 loggers 选项以指定日志发送位置。有关 MCP 服务器选项的详细信息，请参阅 MongoDB MCP 服务器配置选项。
下表显示了 MCP 服务器存储日志文件的默认目录：
操作系统 | 默认日志目录 |
|---|---|
Windows |
|
macOS 和 Linux |
|
要更改日志路径，设立以下选项之一：
logPathJSON配置文件中或启动 MCP 服务器时命令行上的选项MDB_MCP_LOG_PATH环境变量
连接字符串问题
确保您的配置文件正确，并且您为MongoDB 部署使用有效的连接字符串。
有关连接字符串格式和示例，请参阅 连接字符串。
HTTP传输问题
如果您使用HTTP传输并遇到连接问题：
验证您的客户端连接URL是否包含
/mcp端点路径：http://<server-address>:3000/mcp 如果连接到远程服务器（不同的计算机、容器或云实例），请确保使用
--httpHost=0.0.0.0启动服务器以接受远程连接：npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --readOnly 确保指定端口已打开并可从客户端计算机访问。
Atlas Tools 与Database Tools配置指南
Overview
MongoDB MCP 服务器提供三类主要工具：用于管理Atlas基础架构的Atlas工具、用于管理本地部署的本地Atlas工具（类似于Atlas CLI提供的工具）以及用于数据操作的数据库工具。下表比较了每个工具的配置。
配置比较表
配置方面 | Atlas Tools | 本地Atlas工具 | Database Tools |
|---|---|---|---|
身份验证要求 | Required: Atlas API credentials • apiClientId (Service Account ID)• apiClientSecret (Service Account Secret) | Required: Docker runtime • No additional credentials needed • Automatically manages local deployments | Optional: Multiple connection methods • Pre-configured connection string • Atlas credentials for atlas-connect-cluster• Runtime connection via connect tool• Local deployment via atlas-local-connect-deployment |
连接方法 | API-based connection to Atlas Management API • No direct database connection needed • Uses Atlas REST API endpoints | Local deployment management • Uses Docker containers • No external network access required | Direct connection to MongoDB database. Multiple options available: • Configured connection string • Runtime connection prompt • Atlas cluster discovery • Local deployment connection |
权限要求 | Service Account Roles (Atlas project-level): • Project Read Only (minimum for read operations)• Project Owner (for cluster creation/management)• Organization Owner (for project creation) | System Requirements: • Docker runtime permissions • Local file system access • Container management capabilities | Database User Roles (when applicable): • readAnyDatabase (read-only mode)• readWriteAnyDatabase (full operations)• Custom roles for specific databases/collections |
配置选项 | Environment Variables: MDB_MCP_API_CLIENT_ID orMDB_MCP_API_CLIENT_SECRETCommand Line: • --apiClientId• --apiClientSecret | Environment Variables: • DOCKER_HOST (optional)Command Line: • No specific MCP configuration required • Automatically detects Docker runtime | Environment Variables (optional): MDB_MCP_CONNECTION_STRINGCommand Line (optional): • Connection string as positional argument: --connectionStringRuntime Methods: • Interactive connection via LLM prompts • Atlas credential-based discovery |
只读模式影响 | • Read operations: ✅ Available • Cluster inspection: ✅ Available • Cluster creation: ❌ Disabled • User management: ❌ Disabled | • Local deployment creation: ✅ Available • Deployment inspection: ✅ Available • Container management: ✅ Available • No read-only restrictions | • Read operations: ✅ Available • Query operations: ✅ Available • Aggregations: ✅ Available as long as they don't have a $out or $merge stage.• Insert/Update/Delete: ❌ Disabled • Index creation: ❌ Disabled |
工具类别 | Can be disabled with: --disabledTools atlas orMDB_MCP_DISABLED_TOOLS="atlas" | Can be disabled with: --disabledTools atlas orMDB_MCP_DISABLED_TOOLS="atlas" | Can be disabled with: --disabledTools mongodb orMDB_MCP_DISABLED_TOOLS="mongodb" |
网络要求 | Outbound HTTPS to Atlas API: • Standard internet connection | Local Docker Network: • Docker daemon access • Local port availability • No external network requirements | Connection to MongoDB cluster (when applicable): • Atlas: mongodb+srv:// (port 27017)• Sharded clusters (port 27016) • Self-managed: Custom host/port • Local deployments: Docker network • VPC/network access as required |
可用操作 | • Organization management • Project management • Cluster lifecycle (create, inspect, delete) • Database user management • Access list configuration • Performance Advisor recommendations • Alert management | • Local deployment creation and management • Container lifecycle operations • Local cluster configuration • Development environment setup • Testing deployment management | • CRUD operations (find, insert, update, delete) • Aggregation pipelines • Index management • Collection and database administration • Schema inspection • Vector search operations • Data export |
错误场景 | Missing API Credentials: Atlas tools return: "Atlas API credentials not configured" Insufficient Permissions: HTTP 403 errors from Atlas API | Docker Unavailable: "Docker daemon not running" or "Docker not installed" Container Issues: Port conflicts, resource constraints | Connection Failures (when configured): Network timeouts, authentication failures Missing Database Permissions: MongoDB authorization errors |
临时凭证 | Not applicable: Uses persistent service account credentials | Not applicable: Local deployments use container-managed authentication | Auto-generated database users (when applicable): When using Atlas API credentials without connection string: • Random username/password • 4-hour expiration by default • Automatic role assignment |
数据库连接方法
数据库工具支持多种连接方法，以满足不同的使用案例和安全要求：
connectionString预配置连接字符串：通过CLI、环境变量或配置文件配置 ，以实现持久数据库访问权限。Atlas集群连接：使用
atlas-connect-cluster工具和Atlas API凭证自动发现并连接到Atlas集群。运行时连接：使用
connect工具在 LLM 对话期间以交互方式提供连接字符串 — 无需预先配置。本地部署连接：将
atlas-local-connect-deployment与Docker结合使用来创建并连接到本地Atlas部署 - 需要Docker ，但无需配置。
安全建议：
生产数据库：使用通过环境变量或Atlas API凭证预先配置的连接字符串，实现安全、自动化的连接。
开发/测试：运行时连接或本地部署提供了灵活性，无需持久配置。
聊天安全性：避免使用运行时连接方法，除非您确信聊天历史记录不会被存储或与第三方共享。