使用说明

项目简介

'mongo-mcp' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接大型语言模型 (LLM) 和 MongoDB 数据库。它充当 LLM 的后端，提供了一系列工具，使 LLM 能够以自然语言指令操作 MongoDB 数据库，例如查询数据、检查集合结构、管理索引和执行文档CRUD操作。

主要功能点

集合模式检查：允许 LLM 理解 MongoDB 集合的结构，包括字段名称和数据类型。
文档查询与过滤：支持 LLM 使用自然语言查询 MongoDB 文档，并进行复杂的条件过滤。
索引管理：使 LLM 能够管理 MongoDB 索引，包括创建、删除和列出索引，以优化数据库性能。
文档操作：提供工具让 LLM 可以插入、更新和删除 MongoDB 文档。
数据库和集合列表：允许 LLM 获取数据库和集合的列表信息，了解可操作的数据范围。
聚合管道：支持执行 MongoDB 聚合管道操作，进行更复杂的数据分析和处理。

安装步骤

安装 Node.js: 确保你的电脑上安装了 Node.js (版本 18 或更高)。你可以从 Node.js 官网下载并安装。
安装 npx: npx 通常随 Node.js 一起安装。如果未安装，可以使用 npm 安装：'npm install -g npx'。

克隆仓库: 使用 git 克隆 'mongo-mcp' 仓库到本地：

git clone https://github.com/adiom-data/mongo-mcp

进入仓库目录: 打开终端，进入克隆下来的 'mongo-mcp' 目录：
```
cd mongo-mcp
```
安装依赖: 运行 npm 命令安装项目所需的依赖包：
```
npm install
```

服务器配置

要将 'mongo-mcp' 服务器与 MCP 客户端连接（例如 Claude Desktop），需要在 MCP 客户端的配置文件中添加服务器配置信息。通常，配置文件是 JSON 格式。以下是一个配置示例，你需要根据你的 MongoDB 连接信息进行调整：

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

配置参数说明:

'"mongodb"': 服务器名称，可以自定义，用于在 MCP 客户端中标识这个 MongoDB 服务器连接。
'"command"': 启动服务器的命令。这里使用 'npx'，它会查找并执行 'mongo-mcp' npm 包。
'"args"': 传递给启动命令的参数数组。
- '"mongo-mcp"': 指定要执行的 npm 包名称，即 'mongo-mcp' 服务器。
- '"mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"': MongoDB 连接 URL。请务必替换 '<username>'、'<password>'、'<host>'、'<port>' 和 '<database>' 为你实际的 MongoDB 数据库连接信息。 'authSource=admin' 通常用于指定认证数据库。

本地开发模式配置 (可选): 如果你希望在本地开发环境中运行服务器，并且已经构建了项目，可以使用以下配置直接运行编译后的 JavaScript 文件：

{
  "mcpServers": {
    "mongodb-local": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

'"mongodb-local"': 本地开发服务器的自定义名称。
'"command"': 使用 'node' 命令直接运行 JavaScript 文件。
'"args"':
- '"dist/index.js"': 指向编译后的服务器入口文件路径。
- '"mongodb://root:example@localhost:27017/test?authSource=admin"': 本地 MongoDB 连接 URL (示例，根据实际情况修改)。

基本使用方法

启动 MongoDB 服务器: 确保你的 MongoDB 数据库服务器正在运行，或者使用仓库提供的 Docker Compose 脚本启动测试沙箱环境 (参考仓库 README)。
配置 MCP 客户端: 将上述 "服务器配置" 部分生成的 JSON 配置添加到你的 MCP 客户端的配置文件中。
启动 MCP 服务器: 当 MCP 客户端尝试连接到配置的 '"mongodb"' 服务器时，服务器会自动启动 (通过 'npx mongo-mcp' 方式)。如果使用本地开发模式，你可能需要手动在项目根目录运行 'npm run start' 或 'node dist/index.js your-mongodb-url' 来启动服务器。
在 LLM 中使用自然语言指令: 在支持 MCP 的 LLM 应用中（如 Claude），你可以使用自然语言指令来指示 LLM 使用 'mongo-mcp' 服务器提供的数据库工具。例如：
- '列出数据库中有哪些集合？' (对应 'listCollections' 工具)
- '展示 users 集合的结构是什么样的？' (需要结合自定义 Prompt 和工具链来实现)
- '查找所有在旧金山的用户。' (对应 'find' 工具)
- '在 products 集合中插入一个名为 'Gaming Laptop' 的新产品。' (对应 'insertOne' 工具)

关键词