# MongoDB 3.6+ MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
[![MongoDB Version](https://img.shields.io/badge/mongodb-%3E%3D3.6-green)](https://www.mongodb.com)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server implementation for MongoDB 3.6 and above. This server enables AI assistants like Claude to interact with MongoDB databases through a standardized interface.

## Features

- ✅ **MongoDB 3.6+ Compatible**: Works with MongoDB 3.6 and all newer versions
- 🔧 **Standard MCP Protocol**: Implements the Model Context Protocol specification
- 🛠️ **Essential Operations**: List collections, find documents, count, and aggregations
- 🔒 **Environment-based Configuration**: Secure configuration through environment variables
- 📦 **Zero Default Values**: Requires explicit configuration for security

## Installation

### Prerequisites

- Node.js >= 14.0.0
- MongoDB 3.6 or higher
- Access to a MongoDB instance

### Install from npm

```bash
npm install -g mongodb36-mcp-server
```

### Install from source

```bash
git clone https://github.com/linzi007/mongodb36-mcp-server.git
cd mongodb36-mcp-server
npm install
chmod +x index.js
```

## Configuration

This server requires environment variables to be set. **No default values are provided** to ensure secure and explicit configuration.

### Required Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `MONGODB_CONNECTION_STRING` | MongoDB connection URI | `mongodb://localhost:27017` |
| `MONGODB_DB_NAME` | Database name to use | `myDatabase` |

### Setting Environment Variables

**Linux/macOS:**
```bash
export MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
export MONGODB_DB_NAME="myDatabase"
```

**Windows (Command Prompt):**
```cmd
set MONGODB_CONNECTION_STRING=mongodb://localhost:27017
set MONGODB_DB_NAME=myDatabase
```

**Windows (PowerShell):**
```powershell
$env:MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
$env:MONGODB_DB_NAME="myDatabase"
```

## Usage

### Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

#### Option 1: Using npx (Recommended - if published to npm)

```json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb36-mcp-server"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "myDatabase"
      }
    }
  }
}
```

#### Option 2: Using local installation

```json
{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["/absolute/path/to/mongodb36-mcp-server/index.js"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "myDatabase"
      }
    }
  }
}
```

#### Option 3: Using GitHub repository directly

```json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "github:linzi007/mongodb36-mcp-server"],
      "env": {
        "MONGODB_CONNECTION_STRING": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "myDatabase"
      }
    }
  }
}
```

### Running Directly

```bash
MONGODB_CONNECTION_STRING="mongodb://localhost:27017" \
MONGODB_DB_NAME="myDatabase" \
node index.js
```

## Available Tools

The server provides the following MCP tools:

### 1. `list_collections`

List all collections in the database.

**Example:**
```
List all collections in the database
```

### 2. `find`

Find documents in a collection.

**Parameters:**
- `collection` (required): Collection name
- `filter` (optional): MongoDB query filter
- `limit` (optional): Maximum number of documents (default: 10)

**Example:**
```
Find documents in the "users" collection where age > 25, limit 5
```

### 3. `find_one`

Find a single document in a collection.

**Parameters:**
- `collection` (required): Collection name
- `filter` (optional): MongoDB query filter

**Example:**
```
Find one document in the "users" collection where email is "user@example.com"
```

### 4. `count`

Count documents in a collection.

**Parameters:**
- `collection` (required): Collection name
- `filter` (optional): MongoDB query filter

**Example:**
```
Count documents in the "orders" collection where status is "completed"
```

### 5. `aggregate`

Run an aggregation pipeline.

**Parameters:**
- `collection` (required): Collection name
- `pipeline` (required): Array of aggregation stages

**Example:**
```
Run aggregation on "sales" collection to group by product and sum quantities
```

## Security Considerations

### Connection String Security

- ⚠️ **Never commit credentials to version control**
- ✅ Use environment variables for sensitive data
- ✅ Consider using MongoDB connection string with authentication: `mongodb://username:password@host:port`
- ✅ Use SSL/TLS for production: `mongodb://host:port?ssl=true`

### Network Security

- 🔒 Ensure MongoDB instance is not exposed to the public internet
- 🔒 Use firewall rules to restrict access
- 🔒 Enable MongoDB authentication and authorization
- 🔒 Use VPN or SSH tunneling for remote connections

### Best Practices

1. **Use read-only credentials** when possible
2. **Limit database access** to only required collections
3. **Monitor query performance** to prevent resource exhaustion
4. **Set connection limits** in MongoDB
5. **Use separate databases** for development and production

## Development

### Project Structure

```
mongodb36-mcp-server/
├── index.js          # Main server implementation
├── package.json      # Package configuration
├── README.md         # This file
├── LICENSE           # MIT License
└── .gitignore        # Git ignore rules
```

### Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Troubleshooting

### Error: MONGODB_CONNECTION_STRING environment variable is required

**Solution:** Set the `MONGODB_CONNECTION_STRING` environment variable before running the server.

### Error: Failed to connect to MongoDB

**Possible causes:**
- MongoDB is not running
- Incorrect connection string
- Network firewall blocking connection
- Authentication failure

**Solution:** 
- Verify MongoDB is running: `mongo --version`
- Test connection: `mongo "your-connection-string"`
- Check firewall settings
- Verify credentials

### Error: Database not found

**Solution:** Ensure the database name in `MONGODB_DB_NAME` exists or will be created on first write.

## Examples

### Basic Query Example

```javascript
// In Claude Desktop, you can ask:
"Show me all users in the users collection"

// This will call the find tool:
{
  "collection": "users",
  "filter": {},
  "limit": 10
}
```

### Aggregation Example

```javascript
// In Claude Desktop, you can ask:
"Calculate the average order value by customer from the orders collection"

// This will call the aggregate tool:
{
  "collection": "orders",
  "pipeline": [
    {
      "$group": {
        "_id": "$customer_id",
        "avgOrderValue": { "$avg": "$total" }
      }
    }
  ]
}
```

## Compatibility

### MongoDB Versions

- ✅ MongoDB 3.6.x
- ✅ MongoDB 4.0.x
- ✅ MongoDB 4.2.x
- ✅ MongoDB 4.4.x
- ✅ MongoDB 5.0.x
- ✅ MongoDB 6.0.x
- ✅ MongoDB 7.0.x

### Node.js Versions

- ✅ Node.js 14.x
- ✅ Node.js 16.x
- ✅ Node.js 18.x
- ✅ Node.js 20.x

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol specification
- [MongoDB Node.js Driver](https://mongodb.github.io/node-mongodb-native/) - Official MongoDB driver
- [Anthropic](https://www.anthropic.com) - For developing Claude and the MCP specification

## Support

- 📖 [Documentation](https://github.com/linzi007/mongodb36-mcp-server)
- 🐛 [Issue Tracker](https://github.com/linzi007/mongodb36-mcp-server/issues)
- 💬 [Discussions](https://github.com/linzi007/mongodb36-mcp-server/discussions)

## Related Projects

- [MCP Specification](https://github.com/modelcontextprotocol/specification)
- [Claude Desktop](https://claude.ai/desktop)
- [MongoDB Official Drivers](https://www.mongodb.com/docs/drivers/)

---

**Made with ❤️ for the AI and MongoDB communities**