MongoDB MCP Server

A Model Context Protocol (MCP) server that provides Claude with the ability to interact with MongoDB databases. This implementation allows Claude to perform a wide range of MongoDB operations, including querying, aggregation, data manipulation (CRUD), and database management directly from the conversation.

Overview

This MongoDB MCP server implements the Model Context Protocol to create a bridge between Claude and MongoDB databases. It enables Claude to execute MongoDB commands through a standardized interface, making it possible to analyze, manage, and work with your data directly in conversations.

Features

• Comprehensive MongoDB Operations: Query documents (find, findOne), perform aggregations (aggregate), count documents (count), get distinct values (distinct), and sample data (sample).
• Data Manipulation: Insert (insertOne, insertMany), update (updateOne, updateMany), and delete (deleteOne, deleteMany) documents.
• Database Management: List databases (listDatabases), list collections (listCollections), and drop collections (dropCollection).
• Query Analysis: Get execution plans for aggregation pipelines (explain).
• Flexible Database Selection: Specify the target database for each operation (defaults to DEFAULT_DATABASE).
• Secure Connection: Connects to MongoDB using environment variables for credentials.
• Simple Integration: Works with Claude Desktop or Cursor through the MCP system.

Installation

Prerequisites

• Node.js (v14 or newer recommended)
• Access to a MongoDB instance (local or Atlas)
• Claude Desktop or Cursor application

Setup

1. Clone this repository (replace ryaker with your username if forked):

   git clone [email protected]:ryaker/mongodb-mcp-server.git
   # Or use HTTPS if preferred
   # git clone https://github.com/ryaker/mongodb-mcp-server.git
   cd mongodb-mcp-server

2. Install dependencies:

   npm install

3. Configure Claude Desktop or Cursor:

   • Find your MCP configuration settings. In Cursor, this is typically in Settings > Extensions > Model Context Protocol. In Claude Desktop, it might be in a config.json file.
   • Add an entry for this server, ensuring you provide the correct absolute path to the mongo-mcp-server.js file and set the required environment variables.

   Example Configuration (adjust path as needed):

   {
     "mcpServers": {
       "mongo-custom-server": { // You can name this key anything descriptive
         "command": "node",
         "args": ["/Volumes/Dev/localDev/MCPServers/CustomMongo_clean/mongo-mcp-server.js"], // <-- Make sure this path is correct!
         "env": {
           "MONGODB_URI": "mongodb+srv://your_username:your_password@your_cluster.mongodb.net/?retryWrites=true&w=majority", // <-- Your MongoDB connection string
           "DEFAULT_DATABASE": "YourDefaultDbName" // <-- Optional: Set a default database
         }
       }
     }
   }

   • Important: Replace the placeholder MONGODB_URI with your actual MongoDB connection string. Ensure the user specified in the URI has the necessary permissions for the operations you intend to perform.
   • The DEFAULT_DATABASE is optional. If set, operations will target this database unless overridden by the database parameter in a tool call.

4. Restart Claude Desktop or Cursor to load the new MCP server.

Tool Reference

The server exposes the following tools. Most tools accept an optional database parameter to specify the target database, otherwise they use the DEFAULT_DATABASE set in the environment variables.

Querying & Reading

1. aggregate: Run a MongoDB aggregation pipeline.
   • collection (string, required): Name of the collection.
   • pipeline (array, required): Aggregation pipeline stages.
   • database (string, optional): Target database.
2. sample: Get random sample documents.
   • collection (string, required): Name of the collection.
   • count (number, optional, default: 5, max: 10): Number of documents to sample.
   • database (string, optional): Target database.
3. explain: Get the execution plan for an aggregation pipeline.
   • collection (string, required): Name of the collection.
   • pipeline (array, required): Aggregation pipeline stages.
   • database (string, optional): Target database.
4. find: Find documents matching a query.
   • collection (string, required): Name of the collection.
   • filter (object, optional, default: {}): Query filter.
   • projection (object, optional, default: {}): Fields to include/exclude.
   • limit (number, optional, default: 10, max: 100): Max documents to return.
   • sort (object, optional, default: {}): Sort criteria.
   • database (string, optional): Target database.
5. findOne: Find a single document matching a query.
   • collection (string, required): Name of the collection.
   • filter (object, required): Query filter.
   • projection (object, optional, default: {}): Fields to include/exclude.
   • database (string, optional): Target database.
6. count: Count documents matching a query.
   • collection (string, required): Name of the collection.
   • filter (object, optional, default: {}): Query filter.
   • database (string, optional): Target database.
7. distinct: Get distinct values for a field.
   • collection (string, required): Name of the collection.
   • field (string, required): Field name.
   • filter (object, optional, default: {}): Query filter.
   • database (string, optional): Target database.

Data Manipulation (Write/Delete)

8. insertOne: Insert a single document.
   • collection (string, required): Name of the collection.
   • document (object, required): Document to insert.
   • database (string, optional): Target database.
9. insertMany: Insert multiple documents.
   • collection (string, required): Name of the collection.
   • documents (array, required): Array of documents.
   • database (string, optional): Target database.
10. updateOne: Update a single document.
    • collection (string, required): Name of the collection.
    • filter (object, required): Filter to select document.
    • update (object, required): Update operations (e.g., $set).
    • upsert (boolean, optional, default: false): Create if not found?
    • database (string, optional): Target database.
11. updateMany: Update multiple documents.
    • collection (string, required): Name of the collection.
    • filter (object, required): Filter to select documents.
    • update (object, required): Update operations.
    • database (string, optional): Target database.
12. deleteOne: Delete a single document.
    • collection (string, required): Name of the collection.
    • filter (object, required): Filter to select document.
    • database (string, optional): Target database.
13. deleteMany: Delete multiple documents.
    • collection (string, required): Name of the collection.
    • filter (object, required): Filter to select documents.
    • database (string, optional): Target database.

Database/Collection Management

14. listCollections: List all collections in a database.
    • nameOnly (boolean, optional, default: false): Return only names?
    • database (string, optional): Target database.
15. listDatabases: List all databases on the server.
    • nameOnly (boolean, optional, default: true): Return only names?
16. dropCollection: Drop an entire collection.
    • collection (string, required): Name of the collection to drop.
    • confirm (boolean, required): Must be true to confirm deletion.
    • database (string, optional): Target database.

Usage Examples

Querying Data:

User: Find the 5 most recent user documents in the 'users' collection.
Claude: (Calls 'find' with collection='users', limit=5, sort={createdAt: -1})

User: Show me the user document with email '[email protected]'.
Claude: (Calls 'findOne' with collection='users', filter={email: '[email protected]'})

User: How many orders were placed yesterday in the 'orders' collection in the 'sales' database?
Claude: (Calls 'count' with collection='orders', filter={orderDate: {$gte: startOfDay, $lt: endOfDay}}, database='sales')

Aggregating Data:

User: What are the distinct product categories in the 'products' collection?
Claude: (Calls 'distinct' with collection='products', field='category')

User: Show me the total sales per month from the 'orders' collection.
Claude: (Calls 'aggregate' with collection='orders', pipeline=[...])

Modifying Data:

User: Insert a new user document: { name: 'Alice', email: '[email protected]' }
Claude: (Calls 'insertOne' with collection='users', document={ name: 'Alice', email: '[email protected]' })

User: Update the user with email '[email protected]' to set their status to 'active'.
Claude: (Calls 'updateOne' with collection='users', filter={email: '[email protected]'}, update={$set: {status: 'active'}})

User: Delete all log entries older than 30 days from the 'logs' collection.
Claude: (Calls 'deleteMany' with collection='logs', filter={timestamp: {$lt: thirtyDaysAgo}})

Managing Collections:

User: List all collections in the 'staging' database.
Claude: (Calls 'listCollections' with database='staging')

User: Please drop the 'test_data' collection. Confirm deletion.
Claude: (Calls 'dropCollection' with collection='test_data', confirm=true)

Security Considerations

• NEVER hardcode database credentials in the server file or commit them to version control.
• Always use environment variables (MONGODB_URI) for connection strings.
• Create a dedicated MongoDB user for this MCP server with the principle of least privilege. Grant only the permissions necessary for the intended operations.
• Consider using IP Access Lists (whitelisting) in MongoDB Atlas for an additional layer of security.

Troubleshooting

• Connection Issues: Verify MONGODB_URI is correct. Ensure the MongoDB user has permissions and network access (firewalls, IP lists). Check server logs (console.error) via Claude Desktop/Cursor logs.
• Tool Not Found/Working: Ensure the server is running and configured correctly in Claude Desktop/Cursor. Check the MCP server path is correct. Restart Claude/Cursor.
• Permissions Errors: Review the MongoDB user's roles and permissions.

License

MIT License

Acknowledgments

• Model Context Protocol
• MongoDB Node.js Driver