项目介绍
Mongo-MCP
English | 简体中文
这是一个用于MongoDB操作的机器聊天协议（MCP）服务。该服务提供了一整套工具，使大型语言模型（LLMs）能够通过完整的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
该服务器使用标准I/O传输方法，适用于集成支持此传输方法的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：最大连接池大小（默认：1100）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）
开发指南
- 克隆仓库
git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp
- 安装开发依赖
# 使用uv（推荐）
uv sync
# 或使用pip
pip install -e ".[dev]"
- 运行测试
uv run pytest tests/ -v
- 代码结构
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的集成测试
- 隔离组件测试的模拟测试
运行测试套件：
# 运行所有测试
uv run pytest
# 运行带有详细输出的测试
uv run pytest -v
# 运行特定的测试文件
uv run pytest tests/test_tools.py
日志
日志文件默认存储在logs目录中。日志系统支持：
- 可配置的日志级别
- 基于大小的日志文件轮转
- 支持UTF-8编码
- 包含函数名和行号的结构化日志
许可证
MIT
贡献
欢迎通过问题和拉取请求进行贡献。提交PR前，请确保：
- 所有测试通过（
uv run pytest） - 添加了适当的测试用例
- 更新了文档
- 代码遵循现有的风格模式