MongoDB MCP Server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MongoDB MCP Serverlist all databases"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🍃 MongoDB MCP Server
A ready-to-use integration of the MongoDB MCP Server with multiple deployment modes — from a simple local launcher to a fully secured RBAC gateway with Keycloak authentication.
Explore how to connect AI agents and LLM clients (Claude, VS Code Copilot, Cursor, etc.) to your MongoDB databases through the Model Context Protocol.
📋 Table of Contents
# | Section | Description |
1 | Compare the three available modes | |
2 | Get running in 2 minutes (basic mode) | |
3 | Directory layout overview | |
4 | Built-in MCP diagnostic client | |
5 | Connect VS Code to the MCP Server | |
6 | Run the full stack with containers | |
7 | Links to detailed guides | |
8 | All available commands at a glance | |
9 | Official docs and specifications |
Related MCP server: mcp-mongo
🔀 Deployment Modes
This project supports three deployment modes, each adding a layer of security on top of the previous one:
🟢 Basic Mode — Direct Connection
The simplest setup. The MCP Server runs locally and accepts connections without authentication. Best for local development and quick testing.
┌────────────┐ ┌──────────────┐
│ Client │──────────>│ MCP Server │
│ (Agent) │ :8008 │ (MongoDB) │
└────────────┘ └──────────────┘When to use: Solo development, local experiments, testing tools.
📖 See Quick Start below.
🟡 Proxy Mode — OAuth 2.1 Authentication
Adds Keycloak as an OAuth 2.1 Authorization Server and a reverse proxy that validates Bearer tokens before forwarding to the MCP Server. Implements the Delegated Authorization pattern.
┌────────────┐ Bearer ┌──────────┐ ┌──────────────┐
│ Client │──token──>│ Proxy │──────────>│ MCP Server │
│ (Agent) │ │ (RS) │ (no auth) │ (MongoDB) │
└────────────┘ └────┬─────┘ └──────────────┘
│ JWKS
┌────┴─────┐
│ Keycloak │
│ (AS) │
└──────────┘When to use: Shared environments, multiple users, audit requirements.
📖 See
iac/auth-proxy/for the proxy implementation.
🔴 Gateway Mode — RBAC (Role-Based Tool Filtering)
The most secure mode. Extends Proxy Mode by inspecting MCP messages and filtering tools based on the user's Keycloak realm role. Different users see and can execute different sets of tools.
┌────────────┐ Bearer ┌──────────────┐ ┌──────────────┐
│ Client │──token──>│ RBAC Gateway │──────────>│ MCP Server │
│ (Agent) │ │ :4040 │ (no auth) │ (MongoDB) │
└────────────┘ └──────┬───────┘ └──────────────┘
│ JWKS + roles
┌────┴─────┐
│ Keycloak │
│ (AS) │
└──────────┘Role | Mode | Access Level |
🔑 | allow | Full access — all tools (RW) |
📊 | allow | 14 specific tools (RO) |
👁️ | allow | 5 specific tools (RW) |
👤 | deny | All except |
When to use: Production, teams with different access levels, compliance.
📖 See doc/gateway.md for the full guide: architecture, step-by-step setup, Keycloak curl examples, token inspection, and RBAC configuration.
🚀 Quick Start
Prerequisites
Node.js v18+
A MongoDB connection string (Atlas or local)
1. Install dependencies
npm install2. Configure environment
cp .env.example .envEdit .env and set your MongoDB connection string:
MDB_MCP_CONNECTION_STRING=mongodb+srv://user:password@cluster.mongodb.net3. Start the MCP Server
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. Verify with the test client
npm run mcp:client:startAll 7 diagnostic checks should pass (connect, ping, list tools, call tool, list resources, read resource, shutdown).
📁 Project Structure
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🧪 Test Client
The built-in test client implements the full MCP lifecycle and supports both direct and authenticated modes:
# 🟢 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 admin123The client runs a diagnostic suite: initialize, ping, list tools, call a tool, list resources, read a resource, and graceful shutdown.
🆚 VS Code Copilot Integration
The .vscode/mcp.json file provides two server entries:
Server | URL | Auth |
|
| None |
|
| Bearer |
For mongodb-gateway, VS Code will prompt you to paste a Keycloak access token.
Obtain one first (replace user/password as needed):
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));
"Copy the token and paste it when VS Code prompts. See doc/gateway.md for more details and all available users.
🐳 Docker Compose
Run the complete stack with a single command:
npm run mcp:docker:startThis starts three services:
Service | Port | Description |
|
| 🔐 OAuth 2.1 Authorization Server |
|
| 🍃 MongoDB MCP Server |
|
| 🛡️ RBAC Gateway (validates JWT + roles) |
Stop everything:
npm run mcp:docker:stop📜 npm Scripts
Script | Mode | Description |
| 🟢 | Start the MCP Server locally |
| 🟢 | Run diagnostics — direct (no auth) |
| 🔴 | Start the RBAC Gateway locally |
| 🔴 | Run diagnostics — via gateway (with auth) |
| 🟡 | Run diagnostics — via proxy (with auth) |
| 🐳 | Start all Docker services |
| 🐳 | Stop all Docker services |
📖 Documentation
Document | Description |
🔴 RBAC Gateway, full guide with Keycloak examples | |
🟢 Securing Remote MongoDB MCP Servers: An RBAC Gateway Architecture |
📚 References
📄 License
ISC
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ameksike/mongodb-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server