AI导哈

MongoDB协议服务器

一个生产就绪的MongoDB操作协议服务器，提供安全查询、性能监控和全面工具集。

  • by leorosignoli
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 leorosignoli/mongodb-mcp

使用说明

MongoDB MCP服务器

用于MongoDB操作的生产就绪模型上下文协议（MCP）服务器，具有增强的安全性、性能监控和全面的工具。

特性

  • 只读操作：具有内置限制的安全MongoDB查询
  • 综合工具集：7个强大的数据库探索和分析工具
  • 增强安全性：查询清理、速率限制和资源监控
  • 性能监控：内置指标、缓存和超时管理
  • 生产就绪：健康检查、优雅关机和全面日志记录

可用工具

1. query

执行带有安全限制的MongoDB查找查询。

  • 参数: database, collection, query, options
  • 限制：每次查询最多1000个文档
  • 选项：限制、跳过、排序、投影

2. aggregate

运行聚合管道（仅限只读操作）。

  • 参数: database, collection, pipeline, options
  • 限制：最大批量为1000，超时60秒
  • 安全：阻止管道中的写入操作

3. listCollections

列出数据库中的所有集合。

  • 参数: database
  • 退货：集合名称和元数据

4. listDatabases

列出所有可访问的数据库。

  • 参数：无
  • 退货：数据库名称和大小

5. getIndexes

查看集合的索引。

  • 参数: database, collection
  • 退货：指数定义和统计

6. explain

分析查询性能和执行计划。

  • 参数: database, collection, query, options
  • 冗长：queryPlanner、executionStats、所有PlansExecution
  • 退货：详细的执行分析

7. stats

获取集合或数据库统计信息。

  • 参数: database, collection （可选）
  • 退货：存储统计数据、文档计数、索引信息

安装

先决条件

  • Node.js>=18.0.0
  • MongoDB连接（本地或远程）

来自NPM

npm install -g mongodb-mcp-server

来源

git clone https://github.com/your-repo/mongodb-mcp-server
cd mongodb-mcp-server
npm install
npm run build

码头工人

docker build -t mongodb-mcp-server .
docker run -e MONGODB_URI="mongodb://localhost:27017" mongodb-mcp-server

配置

环境变量

变量 描述 默认值 必填
MONGODB_URI MongoDB连接字符串 mongodb://localhost:27017 是的
MONGODB_DATABASE 默认数据库名称 - 否
MONGODB_TIMEOUT 连接超时（ms） 30000 没有
MONGODB_MAX_POOL_SIZE 最大连接池大小 10 没有
MONGODB_MIN_POOL_SIZE 最小连接池大小 2 没有
LOG_LEVEL 日志记录级别 info 没有
RATE_LIMIT_REQUESTS 每分钟最大请求数 100 没有
CACHE_TTL 缓存TTL（秒） 300 没有

连接字符串示例

# Local MongoDB
MONGODB_URI="mongodb://localhost:27017"

# MongoDB Atlas
MONGODB_URI="mongodb+srv://user:password@cluster.mongodb.net/database"

# Replica Set
MONGODB_URI="mongodb://user:password@host1:27017,host2:27017/database?replicaSet=myReplSet"

# With SSL
MONGODB_URI="mongodb://user:password@host:27017/database?ssl=true"

用法

作为MCP服务器

# Start the server
mongodb-mcp-server

# With custom configuration
MONGODB_URI="mongodb://localhost:27017/mydb" mongodb-mcp-server

使用克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mongodb": {
      "command": "mongodb-mcp-server",
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017"
      }
    }
  }
}

查询示例

// Find documents
{
  "database": "ecommerce",
  "collection": "products",
  "query": { "category": "electronics" },
  "options": { "limit": 10, "sort": { "price": -1 } }
}

// Aggregation pipeline
{
  "database": "ecommerce",
  "collection": "orders",
  "pipeline": [
    { "$match": { "status": "completed" } },
    { "$group": { "_id": "$customerId", "totalSpent": { "$sum": "$amount" } } },
    { "$sort": { "totalSpent": -1 } },
    { "$limit": 5 }
  ]
}

// Explain query performance
{
  "database": "ecommerce",
  "collection": "products",
  "query": { "category": "electronics", "price": { "$lt": 500 } },
  "options": { "verbosity": "executionStats" }
}

安全功能

查询限制

  • 只读的：所有写入操作都被阻止
  • 结果限制：每次查询最多1000个文档
  • 超时保护：60秒后查询超时
  • 资源监控：内存和CPU使用情况跟踪

受阻操作

  • drop, dropDatabase
  • insert, insertOne, insertMany
  • update, updateOne, updateMany
  • delete, deleteOne, deleteMany
  • remove, findAndModify
  • createIndex, dropIndex

速率限制

  • 默认值：每分钟100个请求
  • 可通过以下方式配置 RATE_LIMIT_REQUESTS
  • 按连接跟踪

性能特点

缓存

  • 使用5分钟TTL进行查询结果缓存
  • 可配置的缓存大小和过期时间
  • 自动缓存失效

连接管理

  • 具有最小/最大大小的连接池
  • 故障时自动重新连接
  • 健康检查监测

监控

  • 查询执行指标
  • 连接池统计
  • 错误率跟踪
  • 性能警报

发展

构建

npm run build

发展模式

npm run dev

测试

npm test

代码检查

npm run lint
npm run lint:fix

类型检查

npm run typecheck

Docker使用

构建图像

docker build -t mongodb-mcp-server .

运行容器

docker run -e MONGODB_URI="mongodb://host.docker.internal:27017" mongodb-mcp-server

Docker Compose

version: '3.8'
services:
  mongodb-mcp:
    build: .
    environment:
      - MONGODB_URI=mongodb://mongo:27017
      - LOG_LEVEL=debug
    depends_on:
      - mongo
  
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"

故障排除

常见问题

连接被拒绝

# Check MongoDB is running
mongosh --eval "db.runCommand('ping')"

# Test connection string
MONGODB_URI="your-connection-string" mongodb-mcp-server

权限不足

# Ensure user has read permissions
# Add to MongoDB user roles: ["read", "readAnyDatabase"]

内存使用率高

# Reduce query limits
# Increase cache TTL
# Monitor query complexity

调试模式

LOG_LEVEL=debug mongodb-mcp-server

健康检查

服务器提供了一个健康检查端点用于监视：

# Check server status
curl http://localhost:3000/health

安全考虑

  • 网络安全：使用SSL/TLS进行生产连接
  • 认证：始终使用经过身份验证的MongoDB连接
  • 防火墙：仅限制MongoDB访问授权主机
  • 监控：启用安全事件的审核日志记录
  • 更新：保持安全补丁的依赖关系更新

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加新功能的测试
  5. 确保所有测试通过
  6. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

  • GitHub问题：报告bug和功能请求
  • 文档：查看docs/目录以获取详细指南
  • 示例：常见用例请参见示例/目录

相关 MCP