Skip to main content
Glama
az-coder-123

MongoDB MCP Server

by az-coder-123
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

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": "john@example.com",
    "age": 30
  }
}

insert_many

Insert multiple documents.

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

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

delete_one

Delete a single document.

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

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

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/az-coder-123/mongodb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server