MongoDB Intelligence MCP Server

📖 The "Blind AI" Problem

Large Language Models (like Claude, GPT-4, and Cursor) are incredibly smart at writing SQL because SQL has a strict INFORMATION_SCHEMA. AI can instantly read the table structures.

MongoDB is Schemaless. If you point an AI at a raw MongoDB database using the official MCP, the AI is essentially "blind." It has to guess field names, it doesn't know what collections link to each other (no Foreign Keys), and it will constantly hallucinate broken pymongo queries that crash your app.

💡 The Solution

This MCP injects a Dynamic Intelligence Layer between your database and the AI. Before the AI even asks a question, this server:

1. Reverse-Engineers the Schema: Scans all collections to infer exact data types, nullability, and Enums.

2. Proves Foreign Keys: Uses mathematical heuristics and $in queries to physically prove relationships between collections.

3. Anonymizes Data: Detects and masks PII (Personally Identifiable Information) so your sensitive data never leaves your local machine.

Related MCP server: MongoDB

🏗️ Architectural Overview

The server is decoupled into three pluggable layers:

graph TD
    A[AI Agent / LLM] <-->|MCP Protocol via stdio| B[server.py - 14 Exposed Tools]
    
    subgraph "MongoDB Intelligence Server"
    B <--> C[Intelligence Layer]
    C <--> D[Data Access Layer]
    C <--> E[Presentation Layer]
    end
    
    D <-->|Safe, Paginated Queries| F[(Raw MongoDB)]
    
    C --> G[Discovery Engine]
    C --> H[Knowledge Graph]
    C --> I[Security Analyzers]

🛡️ Enterprise Security & Hardening

Standard AI connections are dangerous. We engineered 4 critical safeguards:

1. Memory Protection (OOM Safety Ceiling): If an AI hallucinates a {"$limit": 5000000} query, it will crash your RAM. The MCP dynamically parses all incoming MQL pipelines. If a limit exceeds 1,000, it hard-caps it and returns a Limit enforced: custom (max 1000) flag to the LLM.

2. PII Anonymization: The engine actively scans field names. If it detects password, ssn, email, or phone, it replaces the string payloads with ***MASKED*** before the data hits the AI's context window.

3. Strict Mutation Gating: The server includes Write tools (insert, update, delete, create_index), but they are completely disabled by default via the .env READ_ONLY=true flag.

4. Threaded Concurrency: Reverse-engineering a 5,000-collection ERP database sequentially takes minutes. We use ThreadPoolExecutor (10 workers) to map massive architectures in under ~1.5 seconds.

🛠️ The 14-Tool Arsenal

The MCP exposes exactly 14 functions to the LLM. The AI is strictly forbidden from bypassing these tools.

🔍 Core Data Operations

🧠 Autonomous Intelligence

📊 Multi-Modal Output Generators

🚀 Installation & Setup

1. Prerequisites

• Python 3.11+

• A running MongoDB instance (Local or Atlas)

2. Clone & Install

git clone https://github.com/YOUR_USERNAME/mongodb-intelligence-mcp.git
cd mongodb-intelligence-mcp
pip install -r requirements.txt

3. Configuration

Copy the .env.example file to a new .env file:

cp .env.example .env

Open .env and set your variables:

MONGODB_URI="mongodb://localhost:27017"
# Set to false ONLY if you want the AI to mutate data
READ_ONLY=true 
# Use glob patterns to restrict analysis to specific databases (e.g., tenant_*)
DATABASE_FILTER=

4. Run the Server

python server.py

Note: The server runs on stdio by default, awaiting an MCP Client connection.

🤖 The .cursorrules (Critical for LLM Usage)

If you are using Cursor, Claude Desktop, or Antigravity, you must use the provided .cursorrules file.

This file acts as a strict "Constitution" for the AI. It physically forbids the AI from writing slow, dangerous PyMongo scripts, and forces it to use the MCP tools.

The Auto-Dashboard Rule: The rules file contains an AUTOMATIC REPORT GENERATION RULE. If you ask the AI:

"Find the top 5 highest-paid employees."

The AI will not just print the JSON. Because of the rules, it will autonomously query the MCP, write a background Python script, and generate a beautiful HTML dashboard without you ever explicitly asking for one.

🏗️ Project Structure

d:\MCP\
├── server.py                 # FastMCP entry point (Registers all 14 tools)
├── .cursorrules              # The AI "Constitution"
├── src/
│   ├── data_access/          # Pluggable Layer (PyMongo adapters)
│   ├── intelligence/         # The Brain (Discovery, Graph Theory, Caching, PII)
│   │   └── analyzers/        # Pluggable Security & Compliance scanners
│   └── presentation/         # HTML/PDF/Markdown generators
└── outputs/                  # Timestamped artifacts (gitignored)

🤝 Extensibility

Want to add a new security compliance check (e.g., HIPAA scanning)? You don't need to rewrite the server. Simply drop a new Python script into src/intelligence/analyzers/ by subclassing BaseAnalyzer. The MCP will automatically pick it up, run it during discovery, and inject the findings into the LLM context.