MongoDB MCP Server

# 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: ```bash # 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: ```bash git clone <repository-url> cd learn-mcp-mongo npm install ``` 4. Configure Environment: ```bash 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: ```bash 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: ```json { "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/](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 ``` 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: ```json { "_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: ```json { "_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: ```json [ { "_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: ```bash # 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: ```bash # Watch server logs in real-time tail -f ~/Library/Logs/Claude/mcp*.log ``` 2. MongoDB Operations: ```bash # Check MongoDB status mongosh use mcp-mongo db.users.find() # List all users ``` 3. Test Tools Manually: ```bash # 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