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.

Related MCP server: jobs-mcp-server

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:

npm install

2. Create your env file:

cp .env.example .env

3. Update .env values:

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:

npm run seed

5. Build the server:

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:

npm start

Development

Run directly with TypeScript:

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):

   {
     "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.