# 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](https://nodejs.org/) | v18 or higher |
| [Docker Desktop](https://www.docker.com/products/docker-desktop) | Latest |
| [Claude Desktop](https://claude.ai/download) | Latest |

---

## Step 1 — Install Docker Desktop

1. Download Docker Desktop from [docker.com/products/docker-desktop](https://www.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:
```powershell
wsl --update
```

Verify Docker works by opening a regular PowerShell (not as Administrator) and running:
```powershell
docker --version
```

---

## Step 2 — Run MongoDB in Docker

Pull the official MongoDB image (one time only):
```powershell
docker pull mongo
```

Start a MongoDB container:
```powershell
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:
```powershell
docker ps
```

You should see `mongodb` in the list with status `Up`.

Test that MongoDB is responding:
```powershell
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:

```powershell
# Start MongoDB
docker start mongodb

# Stop MongoDB
docker stop mongodb

# Check if it's running
docker ps
```

---

## Step 3 — Clone and Install

```bash
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:

```powershell
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:
```powershell
$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.

```json
{
  "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

```powershell
$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](https://github.com/modelcontextprotocol/typescript-sdk) — `@modelcontextprotocol/sdk`
- [MongoDB Node.js Driver](https://www.mongodb.com/docs/drivers/node/current/) — `mongodb`
- [Zod](https://zod.dev/) — `zod`
- [Docker](https://www.docker.com/)
- [Claude Desktop](https://claude.ai/download)

---

## License

MIT