MongoDB MCP

A MongoDB Model Context Protocol (MCP) Server that allows AI agents and MCP clients to interact with MongoDB databases through standardized tools.

Features

• List all collections
• Discover collection schemas
• Fetch collection data
• Query documents
• Insert documents
• Update documents
• Delete documents
• MongoDB Atlas support
• Local MongoDB support
• MCP stdio transport support

---

Installation

Using pip

pip install mongo-mcp

Using uv

uv add mongo-mcp

---

Prerequisites

• Python 3.10+
• MongoDB Local Instance or MongoDB Atlas Cluster

Examples:

mongodb://localhost:27017

or

mongodb+srv://username:password@cluster.mongodb.net

---

Configuration

MongoDB MCP uses environment variables to connect to your database.

Create a .env file:

MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=shipbihar

Environment Variables

Variable	Description	Required
MONGODB_URI	MongoDB connection string	Yes
DATABASE_NAME	Database name	Yes

---

Running the MCP Server

mongo_mcp

or

python -m mongo_mcp.main

The MCP server will start using stdio transport.

---

MCP Client Configuration

Example MCP configuration:

{
  "mcpServers": {
    "mongodb": {
      "command": "mongo_mcp",
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017",
        "DATABASE_NAME": "shipbihar"
      }
    }
  }
}

---

Available Tools

all_collections

Returns all collections in the configured database.

Example Output:

[
  "users",
  "orders",
  "shipments"
]

---

fetch_collection_schema

Returns an inferred schema from a sample document.

Example:

{
  "_id": "ObjectId",
  "name": "str",
  "email": "str",
  "createdAt": "datetime"
}

---

fetch_collection_data

Returns documents from a collection.

Parameters:

{
  "collection_name": "users",
  "limit": 100
}

---

find_document

Find a document using a MongoDB query.

Example:

{
  "collection_name": "users",
  "query": {
    "email": "john@example.com"
  }
}

---

insert_document

Insert a document.

Example:

{
  "collection_name": "users",
  "document": {
    "name": "John",
    "email": "john@example.com"
  }
}

---

update_document

Update matching documents.

Example:

{
  "collection_name": "users",
  "filter_query": {
    "email": "john@example.com"
  },
  "update_data": {
    "role": "admin"
  }
}

---

delete_document

Delete matching documents.

Example:

{
  "collection_name": "users",
  "filter_query": {
    "email": "john@example.com"
  }
}

---

Common Errors

Error: DATABASE_NAME is None

Error:

TypeError: name must be an instance of str, not <class 'NoneType'>

Reason:

MongoDB MCP cannot find the DATABASE_NAME environment variable.

Solution:

Create a .env file:

MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=your_database_name

or export variables manually.

Windows PowerShell:

$env:MONGODB_URI="mongodb://localhost:27017"
$env:DATABASE_NAME="shipbihar"

Linux/macOS:

export MONGODB_URI="mongodb://localhost:27017"
export DATABASE_NAME="shipbihar"

---

Error: Connection Refused

Error:

ServerSelectionTimeoutError

Reason:

MongoDB server is not running.

Solution:

Start MongoDB:

mongod

or verify your Atlas connection string.

---

Error: Authentication Failed

Error:

Authentication failed

Reason:

Incorrect username or password.

Solution:

Verify your MongoDB credentials.

---

Security

Recommended:

• Use dedicated database users
• Restrict permissions when possible
• Avoid connecting with admin credentials
• Store secrets in environment variables

Do NOT:

• Commit .env files to GitHub
• Hardcode MongoDB passwords in code

---

Development

Clone the repository:

git clone <repository-url>
cd mongo-mcp

Create environment:

uv venv
source .venv/bin/activate

Install dependencies:

uv sync

Run locally:

python -m mongo_mcp.main

---

Roadmap

V1

• Collection discovery
• CRUD operations
• Schema inspection

V2

• Aggregation pipelines
• Count documents
• Regex search

V3

• Natural language queries
• Query optimization
• Schema caching

---

License

MIT License

---

Author

Vishnu Bhardwaj

Built for AI Agents, MCP Clients, and MongoDB Developers.

mongo_agent_mcp