mongo-mcp

A local MCP (Model Context Protocol) server that connects Claude Desktop to a real MongoDB database running in Docker. Supports listing, finding, adding, and deleting users via natural language in Claude.

---

What It Does

Exposes four tools Claude can call:

Tool	What it does
list_users	Returns all users in the database
get_user	Finds a user by name or email
add_user	Adds a new user with duplicate email check
delete_user	Deletes a user by their MongoDB _id

---

Prerequisites

Requirement	Version
Node.js	v18 or higher
Docker Desktop	Latest
Claude Desktop	Latest

---

Step 1 — Install Docker Desktop

1. Download Docker Desktop from docker.com/products/docker-desktop
2. Run the installer — all defaults are fine
3. When prompted to enable WSL2, click Yes
4. Restart your computer after installation
5. Open Docker Desktop and wait for it to fully start (whale icon appears in system tray)

If your WSL is outdated, open PowerShell as Administrator and run:

wsl --update

Verify Docker works by opening a regular PowerShell (not as Administrator) and running:

docker --version

---

Step 2 — Run MongoDB in Docker

Pull the official MongoDB image (one time only):

docker pull mongo

Start a MongoDB container:

docker run -d --name mongodb -p 27017:27017 mongo

What each flag means:

• -d — runs in the background so it doesn't lock your terminal
• --name mongodb — gives the container a name you can reference later
• -p 27017:27017 — maps MongoDB's port to your machine so Node.js can connect via localhost:27017

Verify it's running:

docker ps

You should see mongodb in the list with status Up.

Test that MongoDB is responding:

docker exec -it mongodb mongosh --eval "db.runCommand({ ping: 1 })"

You should see { ok: 1 }.

Managing the container day to day

You only need docker run once. After that:

# Start MongoDB
docker start mongodb

# Stop MongoDB
docker stop mongodb

# Check if it's running
docker ps

---

Step 3 — Clone and Install

git clone https://github.com/YOUR_USERNAME/mongo-mcp.git
cd mongo-mcp
npm install

---

Step 4 — Verify the Server Runs

Make sure MongoDB is running first (docker start mongodb), then:

node server.js

You should see:

Connected to MongoDB

The server will sit and wait — that's normal. Hit Ctrl+C to stop it.

---

Step 5 — Connect to Claude Desktop

Claude Desktop reads its config from a JSON file. The correct path depends on how Claude was installed.

Finding your config file

Microsoft Store / MSIX install:

Run this in PowerShell to open the file Claude actually reads:

$pkg = (Get-AppxPackage -Name "*Claude*").PackageFamilyName
$cfg = Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\claude_desktop_config.json"
notepad $cfg

⚠️ The "Edit Config" button inside Claude Desktop opens a different file that the Store version does not read. Always use the PowerShell command above.

Classic install:

%APPDATA%\Claude\claude_desktop_config.json

Config format

Add mongo-mcp to the mcpServers block. Merge it in alongside any existing servers — do not overwrite the whole file.

{
  "mcpServers": {
    "mongo-mcp": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\mongo-mcp\\server.js"
      ]
    }
  }
}

Replace:

• C:\\Program Files\\nodejs\\node.exe with your actual Node.js path. Find it with where.exe node in PowerShell.
• YOUR_USERNAME with your Windows username.

⚠️ Windows paths in JSON require double backslashes. A single \ will cause the config to fail silently.

Fully restart Claude Desktop

Closing the window is not enough — Claude keeps running in the system tray.

1. Right-click the Claude icon in the system tray
2. Select Quit
3. Relaunch Claude Desktop

Verify the connection

$pkg = (Get-AppxPackage -Name "*Claude*").PackageFamilyName
$logDir = Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\logs"
Get-Content "$logDir\mcp.log" -Tail 20

You should see:

[info] [mongo-mcp] Server started and connected successfully
[info] [mongo-mcp] Message from server: {"result":{"tools":[{"name":"list_users"...}]}}

---

Testing

Ask Claude these in order:

1. "List all users" — should say no users yet
2. "Add a user named Dharhshini with email d@example.com"
3. "Add a user with email d@example.com" — should block duplicate
4. "List all users" — should show the new user
5. "Find the user named Dharhshini"
6. "Find the user with email d@example.com"
7. "Delete the user with ID [paste _id from step 4]"
8. "List all users" — should be empty again

---

Project Structure

mongo-mcp/
├── server.js        # MCP server with all four tools
├── package.json
└── README.md

---

Troubleshooting

Symptom	Likely cause	Fix
Connected to MongoDB not shown	MongoDB container not running	Run docker start mongodb
Server not appearing in Claude	Wrong config path or single backslashes	Use the PowerShell command to find config, double all backslashes
Tools don't appear	Claude not fully restarted	Right-click tray → Quit, then relaunch
Invalid ID format on delete	Copied ID incorrectly	Copy the full _id value from list output

---

Built With

• Model Context Protocol SDK — @modelcontextprotocol/sdk
• MongoDB Node.js Driver — mongodb
• Zod — zod
• Docker
• Claude Desktop

---

License

MIT