MongoDB 3.6+ MCP Server

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:

export MONGODB_CONNECTION_STRING="mongodb://localhost:27017"
export MONGODB_DB_NAME="myDatabase"

Windows (Command Prompt):

set MONGODB_CONNECTION_STRING=mongodb://localhost:27017
set MONGODB_DB_NAME=myDatabase

Windows (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

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

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

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Related Projects

• MCP Specification
• Claude Desktop
• MongoDB Official Drivers

---

Made with ❤️ for the AI and MongoDB communities