MongoDB 3.6+ MCP Server

![License: MIT](https://opensource.org/licenses/MIT) ![Node.js Version](https://nodejs.org) ![MongoDB Version](https://www.mongodb.com)

A Model Context Protocol (MCP) 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

npm install -g mongodb36-mcp-server

Install from source

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)

{
  "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

{
  "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

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

Running Directly

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

Use read-only credentials when possible
Limit database access to only required collections
Monitor query performance to prevent resource exhaustion
Set connection limits in MongoDB
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

// 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

// 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 file for details.

Acknowledgments

Model Context Protocol - The protocol specification
MongoDB Node.js Driver - Official MongoDB driver
Anthropic - For developing Claude and the MCP specification

Support

Related Projects

---

Made with ❤️ for the AI and MongoDB communities

mongodb36-mcp-server