MongoDB MCP Server

A robust Model Context Protocol (MCP) server that provides tools and prompts for interacting with a MongoDB database. Built with Node.js and MongoDB, featuring graceful shutdown handling and comprehensive error management.

Features

• MongoDB integration using Mongoose

• User management tools:

  • create-user: Create a new user

  • get-user: Retrieve user by email

  • list-users: List all users with pagination

• Interactive prompts for guided operations

• Graceful shutdown handling

• Comprehensive error management

• Clean single-file implementation

Prerequisites

• Node.js (Latest LTS version)

• MongoDB (v8.0 or higher)

• Claude for Desktop (latest version)

• Visual Studio Code with Cursor extension (for development)

Development Setup

1. Install MongoDB:

   # Using Homebrew on macOS brew tap mongodb/brew brew install mongodb-community # Start MongoDB service brew services start mongodb-community

2. Install Cursor in VS Code:

   • Open VS Code

   • Go to Extensions (Ctrl+Shift+X)

   • Search for "Cursor"

   • Click Install

3. Clone and Setup:

   git clone <repository-url> cd learn-mcp-mongo npm install

4. Configure Environment:

   cp .env.example .env # Edit .env with your MongoDB URI if different from default

Quick Start

1. Clone or download this repository

2. Install dependencies:

   npm install

3. Configure MongoDB:

   • Make sure MongoDB is running locally (default: mongodb://localhost:27017)

   • Or update the .env file with your MongoDB connection string:

     MONGODB_URI=your_mongodb_connection_string

4. Configure Claude for Desktop:

   • Open or create ~/Library/Application Support/Claude/claude_desktop_config.json

   • Add the following configuration:

     { "mcpServers": { "mcp-mongo": { "command": "node", "args": ["/absolute/path/to/server.js"] } } }

5. Start Claude for Desktop

   • The MCP server will start automatically

   • Look for the "Search and tools" icon to access the tools

Using Cursor with MCP Server

1. Install Cursor (AI Code Editor):

   • Download from https://www.cursor.so/

   • Install and open Cursor on your machine

2. Add MCP Server to Cursor:

   • Open Cursor

   • Go to Settings > Integrations > MCP Servers

   • Click Add MCP Server

   • Fill in:

     • Name: mcp-mongo

     • Command: node

     • Arguments: /absolute/path/to/server.js

     • Working Directory: /absolute/path/to/learn-mcp-mongo

   • Save and enable the integration

3. Use Cursor's AI Features:

   • Open your project folder in Cursor

   • Use /help in the command palette for available AI commands

   • Use /edit, /fix, /doc, and other AI features to interact with your code and MCP tools

   • You can now test, debug, and develop your MCP server directly in Cursor with AI assistance

Usage Examples

Creating a User

Finding a User

Project Structure

Available Tools

create-user

Creates a new user in the database.

• Parameters:

  • name: User's full name (string, required)

  • email: User's email address (string, required, unique)

  • age: User's age (number, required)

• Response:

  { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "age": 30, "createdAt": "2025-06-26T00:00:00.000Z" }

get-user

Retrieves a user by their email address.

• Parameters:

  • email: User's email address (string, required)

• Response:

  { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "age": 30, "createdAt": "2025-06-26T00:00:00.000Z" }

list-users

Lists all users in the database with pagination.

• Parameters:

  • limit: Maximum number of users to return (number, optional, default: 10)

• Response:

  [ { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "age": 30, "createdAt": "2025-06-26T00:00:00.000Z" }, // ... more users ]

Available Prompts

create-new-user

An interactive prompt that guides you through the process of creating a new user by asking for:

1. Full Name

2. Email Address

3. Age

Development Guide

Running the Server

1. Start in Development Mode:

   # Run with inspector for debugging npx @modelcontextprotocol/inspector node mcp-server.js # Or run directly npm start

2. Using Cursor in VS Code:

   • Open the project in VS Code

   • Use Cursor's AI features:

     • Type /help for Cursor commands

     • Use /edit for code suggestions

     • Use /doc to generate documentation

     • Use /fix to get error fixes

Debugging

1. Check Server Logs:

   # Watch server logs in real-time tail -f ~/Library/Logs/Claude/mcp*.log

2. MongoDB Operations:

   # Check MongoDB status mongosh use mcp-mongo db.users.find() # List all users

3. Test Tools Manually:

   # Using curl to test tools (when running in HTTP mode) curl -X POST http://localhost:3000/tools/list-users

Server Features

1. Graceful Shutdown:

   • Handles SIGINT, SIGTERM, SIGHUP signals

   • Closes MongoDB connections properly

   • Logs shutdown process

2. Error Handling:

   • MongoDB connection errors

   • Tool execution errors

   • Uncaught exceptions

   • Unhandled rejections

3. Performance Options:

   • MongoDB connection timeout: 5s

   • Heartbeat frequency: 2s

   • User listing pagination

Troubleshooting

1. Make sure MongoDB is running and accessible

2. Check Claude for Desktop logs at ~/Library/Logs/Claude/mcp*.log

3. Verify the server.js path in claude_desktop_config.json is correct

4. Restart Claude for Desktop after configuration changes