MCP MongoDB Server

NPM 版本 NPM 下载量 NPM 许可证

一个模型上下文协议服务器，使大型语言模型能够与 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 操作

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

大型语言模型集成

集合补全以增强大型语言模型交互
模式推断以改进上下文理解
集合分析以获取数据洞察

安装

全局安装

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 桌面版配置中使用环境变量：

{
  "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 桌面版集成

手动配置

将服务器配置添加到 Claude 桌面版的配置文件：

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 服务器可与 Windsurf 和 Cursor 类似于 Claude 桌面版的方式使用。

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 桌面版配置中显示的模式。

自动安装

使用 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 服务器通过 stdio 通信，调试可能具有挑战性。使用 MCP Inspector 以获得更好的可见性：

npm run inspector

这将提供访问浏览器中调试工具的 URL。

运行 evals

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 文件。

kiliczsh/mcp-mongo-server

星标增长

证据时间轴