Mongo Mcp

Mongo-MCP

English | 简体中文

用于 MongoDB 操作的机器聊天协议（MCP）服务。此服务提供一套全面的工具，支持大语言模型（LLM）通过完整的 CRUD 操作、管理任务和高级功能与 MongoDB 数据库交互。

要求

• Python 3.10 或更高版本
• 正在运行的 MongoDB 数据库服务
• 建议使用 uv 运行程序

🚀 功能

📊 数据库管理工具

• list_databases - 列出所有数据库
• create_database - 创建新数据库
• drop_database - 删除数据库
• get_database_stats - 获取数据库统计信息

📦 集合管理工具

• list_collections - 列出数据库中的所有集合
• create_collection - 创建新集合（可选设置）
• drop_collection - 删除集合
• rename_collection - 重命名集合
• get_collection_stats - 获取集合统计信息

📄 文档 CRUD 操作

• insert_document - 插入单个文档
• insert_many_documents - 批量插入多个文档
• find_documents - 查询文档（支持排序、投影和限制数量）
• find_one_document - 查询单个文档
• count_documents - 统计符合查询条件的文档数量
• update_document - 更新文档（单个或批量）
• replace_document - 替换文档
• delete_document - 删除文档（单个或批量）

🔍 索引管理工具

• list_indexes - 列出集合的所有索引
• create_index - 创建常规索引
• create_text_index - 创建文本搜索索引
• create_compound_index - 创建复合索引
• drop_index - 删除索引
• reindex_collection - 重建集合的所有索引

📈 聚合操作

• aggregate_documents - 执行聚合管道操作
• distinct_values - 获取字段的不同值

🔧 监控和管理工具

• get_server_status - 获取 MongoDB 服务状态
• get_replica_set_status - 获取副本集状态
• ping_database - 测试数据库连接
• test_mongodb_connection - 全面测试连接
• get_connection_details - 获取详细的连接信息

🛠️ 技术栈

• Python：主要编程语言
• FastMCP：用于自动生成工具定义的 MCP Python SDK
• PyMongo：MongoDB 官方 Python 驱动程序
• uv：现代 Python 包管理工具

使用方法

直接使用 uvx 运行

uvx run mongo-mcp

服务使用 stdio 传输方式，适合与支持该传输方式的 MCP 客户端集成。

Cursor 配置示例

如果你使用 Cursor 作为开发环境，可以将以下配置添加到 .cursor/mcp.json 文件中，以进行本地调试：

{
    "mcpServers": {
        "mongo-mcp": {
            "command": "uvx",
            "args": [
                "mongo-mcp"
            ],
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017",
                "MONGODB_DEFAULT_DB": "your_database_name",
                "LOG_LEVEL": "INFO"
            }
        }
    }
}

环境变量

基本配置

• MONGODB_URI：MongoDB 连接字符串（默认值："mongodb://localhost:27017"）
• MONGODB_DEFAULT_DB：默认数据库名称（可选）

连接池配置

• MONGODB_MIN_POOL_SIZE：连接池最小大小（默认值：0）
• MONGODB_MAX_POOL_SIZE：连接池最大大小（默认值：100）
• MONGODB_MAX_IDLE_TIME_MS：最大空闲时间，单位为毫秒（默认值：30000）

超时配置

• MONGODB_SERVER_SELECTION_TIMEOUT_MS：服务选择超时时间（默认值：30000）
• MONGODB_SOCKET_TIMEOUT_MS：套接字超时时间（默认值：0 - 无超时）
• MONGODB_CONNECT_TIMEOUT_MS：连接超时时间（默认值：20000）

安全配置

• MONGODB_TLS_ENABLED：启用 TLS 连接（默认值：false）
• MONGODB_AUTH_SOURCE：身份验证源（默认值：admin）
• MONGODB_AUTH_MECHANISM：身份验证机制（SCRAM-SHA-1、SCRAM-SHA-256 等）

性能设置

• MONGODB_READ_PREFERENCE：读取偏好（默认值：primary）
• MONGODB_WRITE_CONCERN_W：写入关注级别（默认值：1）
• MONGODB_READ_CONCERN_LEVEL：读取关注级别（默认值：local）

日志配置

• LOG_LEVEL：日志级别（默认值："INFO"）
  • 可用值：DEBUG、INFO、WARNING、ERROR、CRITICAL
• LOG_MAX_FILE_SIZE：日志文件最大大小（以字节为单位，默认值：10MB）
• LOG_BACKUP_COUNT：备份日志文件数量（默认值：5）

功能标志

• ENABLE_DANGEROUS_OPERATIONS：启用可能存在危险的操作（默认值：false）
• ENABLE_ADMIN_OPERATIONS：启用管理操作（默认值：true）
• ENABLE_INDEX_OPERATIONS：启用索引操作（默认值：true）

开发指南

1. 克隆仓库

git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp

2. 安装开发依赖

# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"

3. 运行测试

uv run pytest tests/ -v

4. 代码结构

• src/mongo_mcp/server.py：MCP 服务实现
• src/mongo_mcp/db.py：MongoDB 核心操作实现
• src/mongo_mcp/config.py：配置管理
• src/mongo_mcp/tools/：MCP 工具实现
  • database_tools.py：数据库和集合管理
  • document_tools.py：文档 CRUD 操作
  • index_tools.py：索引管理
  • aggregation_tools.py：聚合操作
  • admin_tools.py：管理和监控工具
• src/mongo_mcp/utils/：实用工具模块
• tests/：测试用例

测试

该项目包含全面的测试覆盖：

• 所有工具模块的单元测试
• 与 MongoDB 的集成测试
• 用于独立组件测试的模拟测试

运行测试套件：

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

日志记录

默认情况下，日志文件存储在 logs 目录中。日志系统支持：

• 可配置的日志级别
• 根据大小轮转文件
• UTF-8 编码支持
• 包含函数名称和行号的结构化日志

许可证

MIT

贡献

欢迎通过 Issues 和 Pull Requests 贡献。在提交 PR 之前，请确保：

1. 所有测试均通过（uv run pytest）
2. 添加了适当的测试用例
3. 更新了文档
4. 代码遵循现有的风格规范