MCP MongoDB 服务器

---

这是一个模型上下文协议服务器，使大型语言模型能够与 MongoDB 数据库进行交互。该服务器提供了检查集合模式并通过标准化接口执行 MongoDB 操作的能力。

示例

主要特性

智能 ObjectId 处理

• 在字符串 ID 和 MongoDB ObjectId 之间进行智能转换
• 使用 objectIdMode 参数进行配置：
  • "auto"：根据字段名称进行转换（默认）
  • "none"：不进行转换
  • "force"：强制将所有字符串 ID 字段转换为 ObjectId

灵活配置

• 环境变量：
  • MCP_MONGODB_URI：MongoDB 连接 URI
  • MCP_MONGODB_READONLY：设置为 "true" 时启用只读模式
• 命令行选项：
  • --read-only 或 -r：以只读模式连接

只读模式

• 防止写操作（更新、插入、创建索引）
• 使用 MongoDB 的二级读偏好以获得最佳性能
• 适合安全地连接到生产数据库

MongoDB 操作

• 读取操作：
  • 查询文档并可选地分析执行计划
  • 执行聚合管道
  • 统计匹配条件的文档数量
  • 获取集合模式信息
• 写入操作（非只读模式下）：
  • 更新文档
  • 插入新文档
  • 创建索引

LLM 集成

• 收集完成以增强 LLM 交互
• 推断模式以提高上下文理解
• 分析收集数据洞察

安装

全局安装

npm install -g mcp-mongo-server

开发用途

# 克隆仓库
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server

# 安装依赖
npm install

# 构建
npm run build

# 自动重建开发
npm run watch

使用

基本用法

# 使用 MongoDB URI 启动服务器
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database

# 以只读模式连接
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only

环境变量

你可以通过环境变量来配置服务器，这在 CI/CD 管道、Docker 容器或不想在命令参数中暴露连接详情时特别有用：

# 设置 MongoDB 连接 URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"

# 启用只读模式
export MCP_MONGODB_READONLY="true"

# 运行服务器（如果没有提供 URI，则会使用环境变量）
npx -y mcp-mongo-server

在 Claude Desktop 配置中使用环境变量：

{
  "mcpServers": {
    "mongodb-env": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

使用环境变量与 Docker：

# 构建
docker build -t mcp-mongo-server .

# 运行
docker run -it -d -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" -e MCP_MONGODB_READONLY="true" mcp-mongo-server

# 或编辑 docker-compose.yml 并运行
docker-compose up -d

与 Claude Desktop 集成

手动配置

将服务器配置添加到 Claude Desktop 的配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

命令行参数方法：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

环境变量方法：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
      }
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

GitHub 包使用：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

与 Windsurf 和 Cursor 集成

MCP MongoDB 服务器可以像 Claude Desktop 一样与 Windsurf 和 Cursor 集成。

Windsurf 配置

将服务器添加到你的 Windsurf 配置中：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Cursor 配置

对于 Cursor，将服务器配置添加到你的设置中：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

你也可以使用环境变量方法与 Windsurf 和 Cursor，遵循 Claude Desktop 配置中的相同模式。

自动安装

使用 Smithery：

npx -y @smithery/cli install mcp-mongo-server --client claude

使用 mcp-get：

npx @michaellatman/mcp-get@latest install mcp-mongo-server

可用工具

查询操作

• query：执行 MongoDB 查询

  {
    collection: "users",
    filter: { age: { $gt: 30 } },
    projection: { name: 1, email: 1 },
    limit: 20,
    explain: "executionStats"  // 可选
  }
  

• aggregate：运行聚合管道

  {
    collection: "orders",
    pipeline: [
      { $match: { status: "completed" } },
      { $group: { _id: "$customerId", total: { $sum: "$amount" } } }
    ],
    explain: "queryPlanner"  // 可选
  }
  

• count：统计匹配的文档数量

  {
    collection: "products",
    query: { category: "electronics" }
  }
  

写入操作

• update：修改文档

  {
    collection: "posts",
    filter: { _id: "60d21b4667d0d8992e610c85" },
    update: { $set: { title: "Updated Title" } },
    upsert: false,
    multi: false
  }
  

• insert：添加新文档

  {
    collection: "comments",
    documents: [
      { author: "user123", text: "Great post!" },
      { author: "user456", text: "Thanks for sharing" }
    ]
  }
  

• createIndex：创建集合索引

  {
    collection: "users",
    indexes: [
      {
        key: { email: 1 },
        unique: true,
        name: "email_unique_idx"
      }
    ]
  }
  

系统操作

• serverInfo：获取 MongoDB 服务器详情

  {
    includeDebugInfo: true  // 可选
  }
  

调试

由于 MCP 服务器通过标准 I/O 进行通信，调试可能会有挑战性。使用 MCP Inspector 来获得更好的可见性：

npm run inspector

这将提供一个 URL，以便在浏览器中访问调试工具。

运行评估

Evals 包加载了一个 mcp 客户端，然后运行 index.ts 文件，因此在测试之间无需重新构建。可以通过在 npx 命令前缀加载环境变量。完整的文档可以在 这里 找到。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/schemas/tools.ts

许可证

此 MCP 服务器采用 MIT 许可证。这意味着你可以自由使用、修改和分发软件，但需遵守 MIT 许可证的条款和条件。更多详情，请参见项目存储库中的 LICENSE 文件。