Content
# 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
