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

Related MCP server: MongoDB

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

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