# MongoDB MCP Server

A Model Context Protocol (MCP) server for MongoDB operations, enabling AI assistants to interact with MongoDB databases through a standardized interface.

## Features

### Core Operations
- **Database Operations**: List, stats, drop databases
- **Collection Operations**: Create, drop, rename, list collections
- **Document Operations**: Full CRUD (find, insert, update, delete), aggregation
- **Index Operations**: Create, list, drop indexes

### Security & Access Control
- **Permission System**: Role-based access control with allowed/denied databases and collections
- **Read-Only Mode**: Prevent all write operations
- **Query Result Limits**: Configurable maximum results per query
- **Bulk Operation Limits**: Control maximum bulk operations

### Monitoring & Auditing
- **Audit Logging**: Track all operations with timestamps, success/failure status
- **Rate Limiting**: Prevent abuse with configurable request limits
- **Health Check**: Monitor MongoDB connection and server status

### Data Protection
- **Data Masking**: Automatically mask sensitive fields (passwords, tokens, etc.)
- **Confirmation Prompts**: Require confirmation for dangerous operations (drop database/collection)

### Configuration
- **Configuration File**: Support for JSON configuration files
- **Environment Variables**: All settings configurable via environment variables
- **Connection Pooling**: MongoDB driver connection pooling

## Installation

```bash
npm install mongodb-mcp
```

Or from source:

```bash
git clone https://github.com/az-coder-123/mongodb-mcp.git
cd mongodb-mcp
npm install
npm run build
```

## Configuration

### Configuration File

Create a `mcp-settings.json` file in your project root or home directory:

```json
{
  "connectionString": "mongodb://localhost:27017",
  "permissions": {
    "readOnly": false,
    "allowedDatabases": ["myapp", "analytics"],
    "deniedDatabases": ["admin", "config"],
    "allowedCollections": {
      "myapp": ["users", "orders", "products"]
    },
    "deniedTools": ["drop_database"],
    "maxQueryResults": 1000,
    "maxBulkOperations": 1000
  },
  "auditLog": {
    "enabled": true,
    "logFilePath": "./logs/audit.log",
    "maxEntries": 10000,
    "logSuccess": true,
    "logFailure": true
  },
  "rateLimit": {
    "enabled": true,
    "maxRequests": 100,
    "windowMs": 60000
  },
  "dataMasking": true,
  "maskedFields": ["password", "secret", "token", "apiKey"]
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MONGODB_URI` | MongoDB connection string | `mongodb://localhost:27017` |
| `MCP_READ_ONLY` | Enable read-only mode | `false` |
| `MCP_ALLOWED_DATABASES` | Comma-separated list of allowed databases | (all allowed) |
| `MCP_DENIED_DATABASES` | Comma-separated list of denied databases | (none) |
| `MCP_DENIED_TOOLS` | Comma-separated list of denied tools | (none) |
| `MCP_MAX_QUERY_RESULTS` | Maximum query results | `1000` |
| `MCP_MAX_BULK_OPERATIONS` | Maximum bulk operations | `1000` |
| `MCP_AUDIT_LOG_ENABLED` | Enable audit logging | `true` |
| `MCP_AUDIT_LOG_PATH` | Audit log file path | (console only) |
| `MCP_RATE_LIMIT_ENABLED` | Enable rate limiting | `true` |
| `MCP_RATE_LIMIT_MAX_REQUESTS` | Max requests per window | `100` |
| `MCP_RATE_LIMIT_WINDOW_MS` | Rate limit window (ms) | `60000` |
| `MCP_DATA_MASKING_ENABLED` | Enable data masking | `true` |
| `MCP_MASKED_FIELDS` | Comma-separated masked fields | `password,secret,token,apiKey` |

## Usage with Claude Desktop

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["/path/to/mongodb-mcp/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017"
      }
    }
  }
}
```

## Available Tools

### Database Operations

#### list_databases
List all databases in the MongoDB instance.

```json
{}
```

#### database_stats
Get statistics for a specific database.

```json
{
  "database": "mydb"
}
```

#### drop_database
⚠️ Drop a database (requires confirmation).

```json
{
  "database": "test_db",
  "confirm": true
}
```

### Collection Operations

#### list_collections
List all collections in a database.

```json
{
  "database": "mydb"
}
```

#### create_collection
Create a new collection.

```json
{
  "database": "mydb",
  "collection": "users",
  "options": {
    "capped": true,
    "size": 1048576,
    "max": 1000
  }
}
```

#### drop_collection
⚠️ Drop a collection (requires confirmation).

```json
{
  "database": "mydb",
  "collection": "temp_data",
  "confirm": true
}
```

### Document Operations

#### find
Find documents with filters, projections, sorting, and pagination.

```json
{
  "database": "mydb",
  "collection": "users",
  "filter": { "age": { "$gte": 18 } },
  "projection": { "name": 1, "email": 1 },
  "sort": { "name": 1 },
  "limit": 10,
  "skip": 0
}
```

#### insert_one
Insert a single document.

```json
{
  "database": "mydb",
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }
}
```

#### insert_many
Insert multiple documents.

```json
{
  "database": "mydb",
  "collection": "users",
  "documents": [
    { "name": "User 1", "email": "user1@example.com" },
    { "name": "User 2", "email": "user2@example.com" }
  ]
}
```

#### update_one
Update a single document.

```json
{
  "database": "mydb",
  "collection": "users",
  "filter": { "email": "john@example.com" },
  "update": { "$set": { "age": 31 } },
  "upsert": false
}
```

#### delete_one
Delete a single document.

```json
{
  "database": "mydb",
  "collection": "users",
  "filter": { "email": "john@example.com" }
}
```

#### aggregate
Run an aggregation pipeline.

```json
{
  "database": "mydb",
  "collection": "orders",
  "pipeline": [
    { "$match": { "status": "completed" } },
    { "$group": { "_id": "$customerId", "total": { "$sum": "$amount" } } },
    { "$sort": { "total": -1 } },
    { "$limit": 10 }
  ]
}
```

### Index Operations

#### create_index
Create an index on a collection.

```json
{
  "database": "mydb",
  "collection": "users",
  "keys": { "email": 1 },
  "options": {
    "unique": true,
    "name": "email_unique_idx"
  }
}
```

### Monitoring Tools

#### health_check
Check MongoDB connection health and server status.

```json
{}
```

#### get_audit_log
Get audit log entries.

```json
{
  "limit": 100,
  "toolName": "insert_one",
  "failuresOnly": false
}
```

#### get_server_config
Get current server configuration.

```json
{}
```

#### set_read_only
Enable or disable read-only mode.

```json
{
  "enabled": true
}
```

## Security Features

### Permission System

Control access to databases and collections:

```json
{
  "permissions": {
    "allowedDatabases": ["myapp"],
    "deniedDatabases": ["admin"],
    "allowedCollections": {
      "myapp": ["users", "orders"]
    },
    "deniedTools": ["drop_database", "drop_collection"]
  }
}
```

### Read-Only Mode

Prevent all write operations:

```bash
MCP_READ_ONLY=true node dist/index.js
```

Or via tool call:

```json
{
  "name": "set_read_only",
  "arguments": { "enabled": true }
}
```

### Confirmation Prompts

Dangerous operations require explicit confirmation:

- `drop_database` requires `"confirm": true`
- `drop_collection` requires `"confirm": true`

### Data Masking

Sensitive fields are automatically masked in responses:

```json
{
  "dataMasking": true,
  "maskedFields": ["password", "secret", "token", "apiKey", "creditCard"]
}
```

### Rate Limiting

Prevent abuse with configurable limits:

```json
{
  "rateLimit": {
    "enabled": true,
    "maxRequests": 100,
    "windowMs": 60000
  }
}
```

## Error Handling

The server implements a comprehensive error handling system with structured error classes, automatic categorization, and actionable recovery suggestions.

### Error Format

The server returns errors in the following format:

```json
{
  "content": [
    {
      "type": "text",
      "text": "VALIDATION_ERROR: Invalid value for 'collection': expected string, got number\n\nSuggestions:\n  1. Check 'collection' parameter\n  2. Refer to documentation for valid values\n\nContext: {\n  \"field\": \"collection\",\n  \"value\": 123,\n  \"expectedType\": \"string\"\n}"
    }
  ],
  "isError": true
}
```

### Error Categories

All errors are categorized for proper handling:

| Category | Description |
|-----------|-------------|
| `VALIDATION` | Invalid input parameters |
| `PERMISSION` | Access denied |
| `RATE_LIMIT` | Too many requests |
| `CONNECTION` | MongoDB connection issues |
| `OPERATION` | Database operation failures |
| `NOT_FOUND` | Resource not found |
| `CONFIGURATION` | Invalid configuration |

### Error Types

The server provides specific error types with recovery suggestions:

- **ValidationError** - Input validation errors
- **PermissionError** - Access denied errors
- **RateLimitError** - Rate limit exceeded
- **ConnectionError** - MongoDB connection failures
- **OperationError** - Database operation failures
- **NotFoundError** - Resource not found
- **ConfigurationError** - Configuration errors
- **ReadOnlyError** - Read-only mode violations
- **BulkLimitError** - Bulk operation limits
- **QueryLimitError** - Query result limits
- **ConfirmationRequiredError** - Dangerous operations without confirmation

### Documentation

For comprehensive error handling documentation, see [docs/error-handling.md](docs/error-handling.md).

This guide includes:
- Complete error classes reference
- Error handling utilities
- Best practices
- Error recovery patterns
- Common troubleshooting scenarios

## Development

### Running in development mode

```bash
npm run dev
```

This will watch for file changes and automatically rebuild.

### Building

```bash
npm run build
```

### Cleaning

```bash
npm run clean
```

## Architecture

```
src/
├── types/
│   └── index.ts          # TypeScript interfaces and types
├── validators/
│   └── index.ts          # Input validation functions
├── handlers/
│   ├── database.ts       # Database operation handlers
│   ├── collection.ts     # Collection operation handlers
│   ├── document.ts       # Document CRUD handlers
│   ├── index-operations.ts # Index operation handlers
│   └── index.ts          # Handler exports
├── resources/
│   └── index.ts          # MCP resource handlers
├── tools/
│   └── index.ts          # Tool definitions
├── utils/
│   ├── permission-checker.ts  # Permission system
│   ├── audit-logger.ts        # Audit logging
│   ├── rate-limiter.ts        # Rate limiting
│   ├── data-masker.ts         # Data masking
│   ├── config-loader.ts       # Configuration loading
│   └── index.ts               # Utility exports
├── server.ts             # Main server class
└── index.ts              # Entry point
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request