Mongo MCP Server

# MongoDB MCP Server A Model Context Protocol (MCP) server that provides MongoDB database access for Claude Code. This server allows you to query MongoDB databases directly from Claude with configurable connection parameters. ## Features - **Master User Management**: Find users by platform ID, email, account ID, or user ID - **Invoice Management**: Search and retrieve invoices by account ID or invoice ID - **Connection Health**: Check MongoDB connection status and health - **Flexible Configuration**: Support for command-line arguments, environment variables, and config files - **Error Handling**: Graceful fallback when database is unavailable ## Installation ### Option 1: Using mcp add (Recommended) ```bash cd your-project-directory mcp add https://github.com/sergei-tofu-fedorov/mongo_mcp.git ``` Then edit the generated `.mcp.json` to add your connection parameters: ```json { "mcpServers": { "mongo_mcp": { "command": "npx", "args": [ "mongo-mcp-server", "--uri", "mongodb://your-host:27017", "--db", "your-database-name" ] } } } ``` ### Option 2: Install from npm (coming soon) ```bash npm install -g mongo-mcp-server ``` ### Option 3: Install from GitHub ```bash npm install -g git+https://github.com/sergei-tofu-fedorov/mongo_mcp.git ``` ### Option 4: Clone and install locally ```bash git clone https://github.com/sergei-tofu-fedorov/mongo_mcp.git cd mongo_mcp npm install npm link # Make it available globally ``` ## Usage ### Method 1: Configure via .mcp.json (Recommended) Add the server to your `.mcp.json` file in any project directory: ```json { "mcpServers": { "mongodb": { "command": "npx", "args": [ "mongo-mcp-server", "--mongo-uri", "mongodb://your-host:27017", "--database", "your-database-name" ] } } } ``` Or with environment variables: ```json { "mcpServers": { "mongodb": { "command": "npx", "args": ["mongo-mcp-server"], "env": { "MONGODB_URI": "mongodb://your-host:27017", "MONGODB_DATABASE": "your-database-name" } } } } ``` ### Method 2: Install locally in project 1. Clone this repo into your project or install as dependency 2. Create a `settings.json` file in the project root: ```json { "mongodb": { "uri": "mongodb://your-host:27017", "database": "your-database-name" } } ``` 3. Add to your `.mcp.json`: ```json { "mcpServers": { "mongodb": { "command": "node", "args": ["./path/to/mongo_mcp/server.js"] } } } ``` ## Configuration Priority The server accepts configuration in the following priority order: 1. **Command-line arguments** (highest priority) ```bash # Full format mongo-mcp-server --mongo-uri mongodb://localhost:27017 --database mydb # Short format mongo-mcp-server --uri mongodb://localhost:27017 --db mydb # Single URI format (with database in path) mongo-mcp-server mongodb://localhost:27017/mydb ``` 2. **Environment variables** ```bash export MONGODB_URI="mongodb://localhost:27017" export MONGODB_DATABASE="mydb" mongo-mcp-server ``` 3. **settings.json file** ```json { "mongodb": { "uri": "mongodb://localhost:27017", "database": "mydb" } } ``` 4. **Default values** (lowest priority) - URI: `mongodb://localhost:27017` - Database: `mcpserver` ## Available Tools ### Connection Management - **`check_connection`**: Check if MongoDB connection is active and healthy ### Master User Tools - **`find-master-user-by-platform-id`**: Find master user by platform ID (case-insensitive search) - Parameters: `platformId` (string), `limit` (number, default: 10) - **`find-master-user-by-email`**: Find master user by email (case-insensitive search) - Parameters: `email` (string), `limit` (number, default: 10) - **`find-master-user-by-id`**: Find a specific master user by their ID - Parameters: `id` (string) - **`find-master-user-by-account-id`**: Find master user by account ID (case-insensitive search) - Parameters: `accountId` (string), `limit` (number, default: 10) ### Invoice Tools - **`find-invoices-by-account-id`**: Find invoices by account ID (case-insensitive search) - Parameters: `accountId` (string), `limit` (number, default: 10) - **`find-invoice-by-id`**: Find a specific invoice by its ID - Parameters: `id` (string) ## Quick Start with mcp add 1. Navigate to any directory where you want to use MongoDB tools: ```bash cd C:\AI\mongo_test ``` 2. Add the MongoDB MCP server: ```bash mcp add https://github.com/sergei-tofu-fedorov/mongo_mcp.git ``` 3. Edit the generated `.mcp.json` file to add your MongoDB connection: ```json { "mcpServers": { "mongo_mcp": { "command": "npx", "args": [ "mongo-mcp-server", "mongodb://your-host:27017/your-database" ] } } } ``` 4. Start Claude Code: ```bash claude-code ``` 5. Use MongoDB tools directly in Claude: ``` find master user by email john@example.com find invoices by account 2djcl2neh9-0f9f3bd0e check mongodb connection status ``` ## Example Usage in Claude Code Once configured, you can use these tools directly in Claude Code: ``` find master user by email john@example.com find invoices by account 2djcl2neh9-0f9f3bd0e check mongodb connection status ``` ## Development ### Requirements - Node.js >= 18.0.0 - MongoDB instance (local or remote) ### Running in Development ```bash git clone https://github.com/sergei-tofu-fedorov/mongo_mcp.git cd mongo_mcp npm install npm run dev # Runs with --watch for auto-reload ``` ### Testing with Different Configurations ```bash # Test with command line args node server.js --mongo-uri mongodb://localhost:27017 --database testdb # Test with environment variables MONGODB_URI=mongodb://localhost:27017 MONGODB_DATABASE=testdb node server.js # Test with settings.json (create the file first) node server.js ``` ## Troubleshooting ### Connection Issues - Verify MongoDB is running and accessible - Check firewall settings and network connectivity - Ensure the URI format is correct: `mongodb://host:port` or `mongodb+srv://cluster.example.com` - Validate database name and permissions ### Permission Issues - Ensure the MongoDB user has read permissions on the target database - Check that the user can access the required collections ### MCP Server Issues - Verify Claude Code can find the server executable - Check the `.mcp.json` configuration syntax - Look for error messages in Claude Code's output ## License MIT ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.