# nodejs-mcp-mongodb

Simple MCP (Model Context Protocol) server built with Node.js, TypeScript, the official MCP SDK, and MongoDB.

## Features

This server provides three MCP tools:

1. `get_business_summary`
   - Returns:
     - total users
     - active users
     - paid users
     - pending payments
     - new users (last 7 days)
2. `get_new_users`
   - Input:
     - `days` (number)
   - Returns users created during the given period.
3. `get_pending_payments`
   - Returns all customers with pending payments.

## Transport

This server currently runs over **stdio** — the standard transport for local MCP servers. The client (e.g. Claude Desktop, Claude Code) launches this server as a subprocess and communicates over stdin/stdout. This is the right choice for a server that runs locally against your own database.

> **Note:** The legacy HTTP+SSE transport is deprecated in the MCP spec in favor of **Streamable HTTP**. This repo doesn't implement a remote transport yet — stdio only, by design, for local use. Streamable HTTP support (for hosting this as a remote/shared server) is a possible future addition.

## Project Structure

- `src/index.ts` - MCP server and tool handlers
- `src/config/env.ts` - environment loading
- `src/db/mongo.ts` - MongoDB connection helper
- `src/services/users.ts` - MongoDB queries for tool responses
- `seed/seed.ts` - sample MongoDB seed script
- `.env.example` - required environment variables

## Setup

1. Install dependencies:
```bash
npm install
```
2. Create your env file:
```bash
cp .env.example .env
```
3. Update `.env` values:
```env
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=mcp_business
```
   Works with a local MongoDB (including Docker) or MongoDB Atlas — just use the appropriate connection string (`mongodb://...` for local, `mongodb+srv://...` for Atlas).
4. Seed sample data:
```bash
npm run seed
```
5. Build the server:
```bash
npm run build
```
   This compiles to `dist/src/index.js` (note: nested under `dist/src/`, not directly in `dist/`).
6. Run the MCP server over stdio:
```bash
npm start
```

## Development

Run directly with TypeScript:
```bash
npm run dev
```

## Connecting to Claude Desktop (macOS)

1. Build the project first (`npm install && npm run build`) and note the **absolute path** to `dist/src/index.js`.
2. Find your Node binary path: `which node` (if you use `nvm`, this will be a versioned path like `~/.nvm/versions/node/vX.X.X/bin/node`).
3. Open Claude Desktop's config file:
   ```
   ~/Library/Application Support/Claude/claude_desktop_config.json
   ```
4. Add a `mcpServers` entry (merge with any existing config — don't overwrite the whole file):
   ```json
   {
     "mcpServers": {
       "mongodb-business": {
         "command": "/absolute/path/to/node",
         "args": ["/absolute/path/to/nodejs-mcp-mongodb/dist/src/index.js"],
         "env": {
           "MONGODB_URI": "mongodb://localhost:27017",
           "MONGODB_DB_NAME": "mcp_business"
         }
       }
     }
   }
   ```
   Use an **absolute path to your Node binary**, not just `"node"` — GUI apps on macOS don't always inherit your shell's PATH.
5. Fully quit Claude Desktop (**Cmd+Q**) and reopen it — the config is only read on startup.
6. Check the tools/connectors panel in the chat box for `mongodb-business` with its 3 tools listed.

## Troubleshooting

- **"Server disconnected" / `MODULE_NOT_FOUND`**: Double-check the build output path is `dist/src/index.js`, not `dist/index.js`.
- **Tool calls fail with a generic internal error**: Check the MCP log at `~/Library/Logs/Claude/mcp-server-<name>.log` on macOS. If the log doesn't show a clear cause, test the server directly by piping a JSON-RPC request into it via stdin to see the raw error.
- **Works when run manually but not from Claude Desktop**: Usually an environment variable mismatch — confirm the `env` block in `claude_desktop_config.json` exactly matches your working `.env` file (the subprocess Claude Desktop spawns does not inherit your shell's environment).
- **Using MongoDB Atlas**: make sure your current IP is allowlisted under Atlas → Network Access, and that any special characters in your password are URL-encoded in the connection string.
- **First tool call fails, and every retry after fails identically**: this indicates a failed initial DB connection getting cached — restart the MCP server process (fully quit and reopen the client) to clear it.

## Known Limitations

- No remote transport (stdio only) — not yet suitable for multi-client/hosted use.
- No automated tests yet.
- Query results from `get_new_users` / `get_pending_payments` are not paginated or capped — fine for demo-scale data, but should be limited before pointing this at a large production collection.