AI导哈

MongoDB MCP服务器

一个即用型的MongoDB MCP服务器集成，支持从简单的本地启动器到完全安全的RBAC网关的多种部署模式，适用于AI代理和LLM客户端连接MongoDB数据库。

  • by ameksike
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 ameksike/mongodb-mcp

使用说明

🍃 MongoDB MCP服务器

即用型集成 MongoDB MCP服务器 具有多种部署模式——从简单的本地启动器到完全 使用Keycloak身份验证的安全RBAC网关。

探索如何连接AI代理和LLM客户端（Claude，VS Code Copilot， 游标等）通过 模型上下文协议.

📋 目录

# 章节 描述
1 部署模式 比较三种可用模式
2 快速开始 在2分钟内开始跑步（基本模式）
3 项目结构 目录布局概述
4 测试客户端 内置MCP诊断客户端
5 VS代码副本 将VS代码连接到MCP服务器
6 Docker Compose 用容器运行整个堆栈
7 文档 详细指南链接
8 npm脚本 所有可用命令一目了然
9 参考文献 官方文件和规范

🔀 部署模式

此项目支持三种部署模式，每种模式都添加一层 安全性在前一个之上：

🟢 基本模式——直接连接

最简单的设置。MCP服务器在本地运行并接受连接 无需身份验证。最适合 本地开发 快速测试。

┌────────────┐           ┌──────────────┐
│   Client   │──────────>│  MCP Server  │
│   (Agent)  │   :8008   │  (MongoDB)   │
└────────────┘           └──────────────┘

何时使用： 独立开发、本地实验、测试工具。

📖 看 快速开始 在......下面

🟡 代理模式——OAuth 2.1身份验证

添加Keycloak作为OAuth 2.1授权服务器和反向代理 其在转发到MCP服务器之前验证承载令牌。 实施 委托授权 图案。

┌────────────┐  Bearer  ┌──────────┐           ┌──────────────┐
│   Client   │──token──>│  Proxy   │──────────>│  MCP Server  │
│   (Agent)  │          │  (RS)    │ (no auth) │  (MongoDB)   │
└────────────┘          └────┬─────┘           └──────────────┘
                             │ JWKS
                        ┌────┴─────┐
                        │ Keycloak │
                        │  (AS)    │
                        └──────────┘

何时使用： 共享环境、多用户、审计要求。

📖 看 iac/auth-proxy/ 用于代理实现。

🔴 网关模式——RBAC（基于角色的工具过滤）

最安全的模式。通过检查MCP消息和 基于用户Keycloak领域角色的过滤工具。不同的用户 查看并可以执行不同的工具集。

┌────────────┐  Bearer  ┌──────────────┐           ┌──────────────┐
│   Client   │──token──>│ RBAC Gateway │──────────>│  MCP Server  │
│   (Agent)  │          │ :4040        │ (no auth) │  (MongoDB)   │
└────────────┘          └──────┬───────┘           └──────────────┘
                               │ JWKS + roles
                          ┌────┴─────┐
                          │ Keycloak │
                          │  (AS)    │
                          └──────────┘
角色 模式 访问级别
🔑 mcp-admin 允许 完全访问--所有工具（RW）
📊 mcp-analyst 允许使用 14个特定工具（RO）
👁️ mcp-viewer 允许 5个特定工具（RW）
👤 mcp-guest 否认 除 atlas 类别（RO）

何时使用： 生产、具有不同访问级别的团队、合规性。

📖 看 doc/gateway.md 完整指南：架构， 逐步设置、Keycloak curl示例、令牌检查和RBAC 配置。

🚀 快速开始

先决条件

  • Node.js v18+
  • MongoDB连接字符串（Atlas或本地）

1.安装依赖项

npm install

2.配置环境

cp .env.example .env

编辑 .env 并设置您的MongoDB连接字符串：

MDB_MCP_CONNECTION_STRING=mongodb+srv://user:password@cluster.mongodb.net

3.启动MCP服务器

npm run mcp:wrapper:start

========================================
  MongoDB MCP Server
========================================
  Status   : running
  URL      : http://127.0.0.1:8008
  Endpoint : http://127.0.0.1:8008/mcp
========================================

4.与测试客户端进行验证

npm run mcp:client:start

所有7个诊断检查都应通过（连接、ping、列出工具、调用工具、， 列出资源、读取资源、关闭）。

📁 项目结构

mongodb-mcp/
├── src/
│   ├── wrapper/                 # 🟢 MCP Server launcher
│   │   ├── index.js             #    Entry point
│   │   └── McpServerLauncher.js #    Process manager (env, spawn, shutdown)
│   ├── gateway/                 # 🔴 RBAC Gateway (OOP, SOLID/GRASP)
│   │   ├── index.js             #    Entry point — config + startup
│   │   ├── GatewayServer.js     #    Controller — HTTP server orchestration
│   │   ├── TokenVerifier.js     #    JWT/JWKS token verification
│   │   ├── RoleResolver.js      #    Role resolution + tool permissions
│   │   ├── McpInterceptor.js    #    MCP message filtering/blocking
│   │   └── ProxyHandler.js      #    HTTP reverse proxy to upstream
│   └── client/index.js          # 🧪 MCP test client (direct & auth modes)
├── cfg/
│   └── roles.json               # 🔧 Role-to-tools mapping config
├── iac/
│   ├── keycloak/
│   │   └── realm-export.json    # 🔐 Keycloak realm (roles, users, scopes)
├── doc/
│   └── gateway.md               # 📖 Full RBAC gateway guide
├── docker-compose.yml           # 🐳 Keycloak + MCP Server + Gateway
├── .env                         # ⚙️  Environment configuration
└── .vscode/mcp.json             # 🆚 VS Code Copilot MCP config

🧪 测试客户端

内置测试客户端实现了完整的 MCP生命周期 并支持直接和认证模式：

# 🟢 Direct — no authentication
npm run mcp:client:start

# 🔴 Via Gateway — with Keycloak token (uses .env defaults)
npm run mcp:client:gateway

# 🔴 Via Gateway — override user from the command line
npm run mcp:client:gateway -- --user mcp-admin --pass admin123

客户端运行一个诊断套件：初始化、ping、列出工具、调用 工具、列出资源、读取资源和优雅关机。

🆚 VS代码副本集成

这 .vscode/mcp.json 文件提供了两个服务器条目：

服务器 URL 身份验证
mongodb http://127.0.0.1:8008/mcp 没有
mongodb-gateway http://127.0.0.1:4040/mcp 持票人

对于 mongodb-gateway，VS Code将提示您粘贴Keycloak访问令牌。 先获取一个（根据需要替换用户/密码）：

curl -s -X POST http://localhost:8080/realms/mcp/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=mcp-client" \
  -d "username=mcp-admin" \
  -d "password=admin123" \
  -d "scope=openid mcp:access" | node -e "
    let d=''; process.stdin.on('data',c=>d+=c);
    process.stdin.on('end',()=>console.log(JSON.parse(d).access_token));
  "

复制令牌并在VS Code提示时粘贴。 看 doc/gateway.md 了解更多详细信息和所有可用用户。

🐳 Docker Compose

用一个命令运行整个堆栈：

npm run mcp:docker:start

这将启动三项服务：

服务 端口 描述
keycloak :8080 🔐 OAuth 2.1授权服务器
mongodb-mcp :8008 🍃 MongoDB MCP服务器
mcp-gateway :4040 🛡️ RBAC网关（验证JWT+角色）

停止一切：

npm run mcp:docker:stop

📜 npm脚本

脚本 模式 描述
npm run mcp:wrapper:start 🟢 在本地启动MCP服务器
npm run mcp:client:start 🟢 运行诊断程序--直接（无身份验证）
npm run mcp:gateway:start 🔴 在本地启动RBAC网关
npm run mcp:client:gateway 🔴 通过网关（带身份验证）运行诊断
npm run mcp:client:auth 🟡 通过代理（带身份验证）运行诊断
npm run mcp:docker:start 🐳 启动所有Docker服务
npm run mcp:docker:stop 🐳 停止所有Docker服务

📖 文档

文档 描述
doc/gateway.md 🔴 RBAC网关，带Keycloak示例的完整指南
doc/remote.md 🟢 保护远程MongoDB MCP服务器：RBAC网关架构

📚 参考文献

📄 许可证

ISC

相关 MCP