MongoDB MCP Server for LLMS

What is Model Context Protocol (MCP)?

• **MCP Clients**: AI assistants like Claude that consume data (e.g., Claude Desktop, Cursor.ai)

• **MCP Servers**: Services that expose data and functionality (like this MongoDB server)

• **Universal Access**: Provides a single protocol for AI assistants to query data from various sources

• **Standardized Connections**: Handles authentication, usage policies, and data formats consistently

• **Sustainable Ecosystem**: Promotes reusable connectors that work across multiple LLM clients

Features

• Collection schema inspection

• Document querying and filtering

• Index management

• Document operations (insert, update, delete)

• Secure database access through connection strings

• Comprehensive error handling and validation

Prerequisites

• [Node.js](https://nodejs.org/) (v18 or higher)

• [MongoDB](https://www.mongodb.com/) instance (local or remote)

• An MCP client like [Claude Desktop](https://claude.ai/download) or [Cursor.ai](https://cursor.sh/)

Quick Start

Installing via Smithery

Cursor.ai Integration

1. Open Cursor.ai and navigate to Settings > Features

2. Look for "MCP Servers" in the features panel

3. Add a new MCP server with the following configuration: - **Name**: `mongodb` - **Command**: `npx` - **Args**: `mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin`

Test Sandbox Setup

1. Start MongoDB using Docker Compose:

1. Seed the database with test data:

Configure Claude Desktop

Local Development Mode:

Test Sandbox Data Structure

Users

• Personal info (name, email, age)

• Nested address with coordinates

• Arrays of interests

• Membership dates

Products

• Product details (name, SKU, category)

• Nested specifications

• Price and inventory info

• Tags and ratings

Orders

• Order details with items

• User references

• Shipping and payment info

• Status tracking

Example Prompts

Basic Operations

Advanced Queries

Index Management

Document Operations

Available Tools

Query Tools

• `listCollections`: Lists available collections in the database

• `find`: Queries documents with filtering and projection

• `insertOne`: Inserts a single document into a collection

• `updateOne`: Updates a single document in a collection

• `deleteOne`: Deletes a single document from a collection

Index Tools

• `createIndex`: Creates a new index on a collection

• `dropIndex`: Removes an index from a collection

• `indexes`: Lists indexes for a collection

Development

• TypeScript for type-safe development

• MongoDB Node.js driver for database operations

• Zod for schema validation

• Model Context Protocol SDK for server implementation

Security Considerations

1. **Create a dedicated MongoDB user** with minimal permissions needed for your use case

2. **Never use admin credentials** in production environments

3. **Enable access logging** for audit purposes

4. **Set appropriate read/write permissions** on collections

5. **Use connection string parameters** to restrict access (e.g., `readPreference=secondary`)

6. **Consider IP allow-listing** to restrict database access **IMPORTANT**: Always follow the principle of least privilege when configuring database access.

How It Works

1. Connects to your MongoDB database using the connection string provided

2. Exposes MongoDB operations as tools that follow the MCP specification

3. Validates inputs using Zod for type safety and security

4. Executes queries and returns structured data to the LLM client

5. Manages connection pooling and proper error handling

Deployment

• Locally via npx (as shown in Quick Start)

• As a global npm package: `npm install -g @coderay/mongo-mcp-server`

• In a Docker container (see Dockerfile in the repository)

• As a service on platforms like Heroku, Vercel, or AWS

Troubleshooting

Common Issues

1. **Connection Errors** - Verify your MongoDB connection string is correct - Check that your MongoDB server is running and accessible - Ensure network permissions allow the connection

2. **Authentication Issues** - Confirm username and password are correct - Verify the authentication database is specified (usually `authSource=admin`) - Check if MongoDB requires TLS/SSL connections

3. **Tool Execution Problems** - Restart Claude Desktop or Cursor.ai completely - Check the logs for detailed error messages: ```bash # macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log ```

4. **Performance Issues** - Consider adding appropriate indexes to frequently queried fields - Use projection to limit the data returned in queries - Use limit and skip parameters for pagination

Getting Help

• Review the [MCP Documentation](https://modelcontextprotocol.io)

• Submit an issue on our [GitHub repository](https://github.com/1rb/mongo-mcp/issues)

Contributing

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add some amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request

License