# 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.