MongoDB 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

npm install mongodb-mcp

Or from source:

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:

{
  "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

{
  "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.

{}

database_stats

Get statistics for a specific database.

{
  "database": "mydb"
}

drop_database

⚠️ Drop a database (requires confirmation).

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

Collection Operations

list_collections

List all collections in a database.

{
  "database": "mydb"
}

create_collection

Create a new collection.

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

drop_collection

⚠️ Drop a collection (requires confirmation).

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

Document Operations

find

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

{
  "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.

{
  "database": "mydb",
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "[email protected]",
    "age": 30
  }
}

insert_many

Insert multiple documents.

{
  "database": "mydb",
  "collection": "users",
  "documents": [
    { "name": "User 1", "email": "[email protected]" },
    { "name": "User 2", "email": "[email protected]" }
  ]
}

update_one

Update a single document.

{
  "database": "mydb",
  "collection": "users",
  "filter": { "email": "[email protected]" },
  "update": { "$set": { "age": 31 } },
  "upsert": false
}

delete_one

Delete a single document.

{
  "database": "mydb",
  "collection": "users",
  "filter": { "email": "[email protected]" }
}

aggregate

Run an aggregation pipeline.

{
  "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.

{
  "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.

{}

get_audit_log

Get audit log entries.

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

get_server_config

Get current server configuration.

{}

set_read_only

Enable or disable read-only mode.

{
  "enabled": true
}

Security Features

Permission System

Control access to databases and collections:

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

Read-Only Mode

Prevent all write operations:

MCP_READ_ONLY=true node dist/index.js

Or via tool call:

{
  "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:

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

Rate Limiting

Prevent abuse with configurable limits:

{
  "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:

{
  "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.

This guide includes:

• Complete error classes reference
• Error handling utilities
• Best practices
• Error recovery patterns
• Common troubleshooting scenarios

Development

Running in development mode

npm run dev

This will watch for file changes and automatically rebuild.

Building

npm run build

Cleaning

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