# MongoDB MCP Server

A Model Context Protocol (MCP) server that provides MongoDB database operations through a standardized interface. This server enables AI assistants to interact with MongoDB databases using CRUD operations, schema analysis, and database management tools.

## Features

- **CRUD Operations**: Create, Read, Update, Delete documents
- **Collection Management**: List collections, get statistics, analyze schemas
- **Index Management**: View and analyze database indexes
- **Schema Analysis**: Automatic document schema detection
- **JSON Serialization**: Proper handling of MongoDB ObjectIds and datetime objects
- **Error Handling**: Comprehensive error messages and validation

## Installation

### Prerequisites

- Python 3.8 or higher
- MongoDB server running
- pip (Python package installer)

### Install as a Package (main)

1. **Clone or download the repository**:
   ```bash
   cd C:/Users/Admin/Downloads/MCP/mcp_mongo
   ```

2. **Create a virtual environment** (recommended):
   ```bash
   uv venv
   ```

3. **Activate the virtual environment**:
   ```bash
   # Windows
   .venv\Scripts\activate
   
   # Linux/Mac
   source .venv/bin/activate
   ```

4. **Install the package in development mode**:
   ```bash
   uv pip install -e .
   ```

## Usage Options

### 1. As a Python Module

Run the server directly as a Python module:

```bash
python -m mcp_mongo.server <mongodb_connection_string>
```

**Examples**:
```bash
# Local MongoDB
python -m mcp_mongo.server "mongodb://localhost:27017/mydb"

# MongoDB with authentication
python -m mcp_mongo.server "mongodb://admin:password@localhost:27017/mydb?authSource=admin"

# MongoDB Atlas
python -m mcp_mongo.server "mongodb+srv://username:password@cluster.mongodb.net/database"
```

### 2. As a Console Script

After installation, use the console script:

```bash
mcp-mongo <mongodb_connection_string>
```

**Examples**:
```bash
# Local MongoDB
mcp-mongo "mongodb://localhost:27017/mydb"

# With authentication
mcp-mongo "mongodb://username:password@localhost:27017/db_name?authSource=admin"
```

### 3. Direct Script Execution

Run the original script directly:

```bash
python mongodb_mcp_server.py <mongodb_connection_string>
```

## MCP Configuration

### For Cursor IDE

Add this to your `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mongodb-simple": {
      "command": "<Path to python.exe in .venv>", 
      "args": ["-m", "mcp_mongo.server", "mongodb://username:password@localhost:27017/mydb?authSource=admin"]
    }
  }
}
```

### For Other MCP Clients

Configure your MCP client to use one of these approaches:

1. **Module approach** (recommended):
   ```json
   {
     "command": "python",
     "args": ["-m", "mcp_mongo.server", "mongodb://username:password@localhost:27017/mydb"]
   }
   ```

2. **Console script approach**:
   ```json
   {
     "command": "mcp-mongo",
     "args": ["mongodb://username:password@localhost:27017/mydb"]
   }
   ```

## Available Tools

### Document Operations

- `list_collections()` - List all collections in the database
- `create_document(collection_name, document)` - Insert a new document
- `read_documents(collection_name, query, limit)` - Find documents
- `read_document_by_id(collection_name, document_id)` - Find document by ID
- `update_document(collection_name, query, update)` - Update documents
- `update_document_by_id(collection_name, document_id, update)` - Update by ID
- `delete_documents(collection_name, query)` - Delete documents
- `delete_document_by_id(collection_name, document_id)` - Delete by ID
- `count_documents(collection_name, query)` - Count documents

### Database Analysis

- `get_collection_schema(collection_name)` - Analyze document schema
- `get_collection_indexes(collection_name)` - View collection indexes
- `get_collection_stats(collection_name)` - Get collection statistics

## Examples

### Basic CRUD Operations

```python
# Create a document
create_document("users", '{"name": "John Doe", "email": "john@example.com", "age": 30}')

# Read documents
read_documents("users", '{"age": {"$gte": 25}}', 10)

# Update a document
update_document("users", '{"name": "John Doe"}', '{"$set": {"age": 31}}')

# Delete documents
delete_documents("users", '{"age": {"$lt": 18}}')
```

### Schema Analysis

```python
# Get schema for a collection
get_collection_schema("users")

# Get collection statistics
get_collection_stats("users")

# Get indexes
get_collection_indexes("users")
```

## Connection String Format

The MongoDB connection string follows this format:

```
mongodb://[username:password@]host[:port]/database[?options]
```

**Common options**:
- `authSource=admin` - Authentication database
- `replicaSet=name` - Replica set name
- `ssl=true` - Enable SSL/TLS
- `retryWrites=true` - Enable retryable writes

## Error Handling

The server provides detailed error messages for:

- **Connection failures** - Invalid connection strings, network issues
- **Authentication errors** - Wrong credentials, missing permissions
- **Query validation** - Invalid JSON, malformed queries
- **Operation errors** - Missing collections, constraint violations

## Development

### Project Structure

```
mcp_mongo/
├── setup.py                 # Package configuration
├── README.md               # This file
├── pyproject.toml          # Main server implementation
├── mcp_mongo/
│   ├── __init__.py         # Package initialization
│   ├── server.py           # Module entry point
|   └── mongodb_mcp_server.py
└── .venv/                  # Virtual environment
```

### Adding New Tools

To add new MCP tools:

1. Add the function to `mongodb_mcp_server.py`
2. Decorate it with `@mcp.tool()`
3. Add proper documentation and error handling
4. Test the new functionality

### Testing

Test the server with a local MongoDB instance:

```bash
# Start MongoDB (if not running)
mongod

# Test the server
python -m mcp_mongo.server "mongodb://username:password@localhost:27017/test"
```

## Troubleshooting

### Common Issues

1. **Connection refused**: Ensure MongoDB is running
2. **Authentication failed**: Check username/password and authSource
3. **Module not found**: Ensure package is installed with `pip install -e .`
4. **Permission denied**: Check file permissions and MongoDB user roles

### Debug Mode

For debugging, check the server logs in stderr. The server provides detailed error messages for troubleshooting.

## License

This project is open source. Please check the license file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions:
- Check the troubleshooting section
- Review the error messages
- Ensure MongoDB is properly configured
- Verify connection string format