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:

3. Clone and Setup:

git clone 
   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:

MONGODB_URI=your_mongodb_connection_string

4. Configure Claude for Desktop:

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

5. Start Claude for Desktop

Using Cursor with MCP Server

1. Install Cursor (AI Code Editor):

2. Add MCP Server to Cursor:

3. Use Cursor's AI Features:

Usage Examples

Creating a User

Create a new user with:
- name: "John Doe"
- email: "john@example.com"
- age: 30

Finding a User

Get user information for email: john@example.com

Project Structure

learn-mcp-mongo/
├── server.js     # Main server file with all functionality
├── .env          # Environment variables
└── package.json  # Project dependencies and scripts

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:

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:

2. Error Handling:

3. Performance Options:

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