# 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

```bash
pip install mongo-mcp
```

## Using uv

```bash
uv add mongo-mcp
```

---

# Prerequisites

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

Examples:

```txt
mongodb://localhost:27017
```

or

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

---

# Configuration

MongoDB MCP uses environment variables to connect to your database.

Create a `.env` file:

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

```bash
mongo_mcp
```

or

```bash
python -m mongo_mcp.main
```

The MCP server will start using stdio transport.

---

# MCP Client Configuration

Example MCP configuration:

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

```json
[
  "users",
  "orders",
  "shipments"
]
```

---

## fetch_collection_schema

Returns an inferred schema from a sample document.

Example:

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

---

## fetch_collection_data

Returns documents from a collection.

Parameters:

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

---

## find_document

Find a document using a MongoDB query.

Example:

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

---

## insert_document

Insert a document.

Example:

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

---

## update_document

Update matching documents.

Example:

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

---

## delete_document

Delete matching documents.

Example:

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

---

# Common Errors

## Error: DATABASE_NAME is None

Error:

```txt
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:

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

or export variables manually.

Windows PowerShell:

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

Linux/macOS:

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

---

## Error: Connection Refused

Error:

```txt
ServerSelectionTimeoutError
```

Reason:

MongoDB server is not running.

Solution:

Start MongoDB:

```bash
mongod
```

or verify your Atlas connection string.

---

## Error: Authentication Failed

Error:

```txt
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:

```bash
git clone <repository-url>
cd mongo-mcp
```

Create environment:

```bash
uv venv
source .venv/bin/activate
```

Install dependencies:

```bash
uv sync
```

Run locally:

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