mcp-mongo

MongoDB MCP Server

A Model Context Protocol (MCP) server for MongoDB integration that provides AI systems with database access and management capabilities through a standardized interface.

Overview

This MongoDB MCP server enables AI systems to perform various MongoDB operations including:

• Creating databases and collections
• Inserting data into collections
• Querying data using natural language
• Managing product reviews and inventory
• Handling support tickets
• Analyzing shipping locations and inventory capacity
• Generating analytics insights

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• MongoDB (local installation or MongoDB Atlas account)

Installation

1. Clone the repository:

git clone <repository-url>
cd mongo-mcp

2. Install dependencies:

npm install

3. Create a .env file in the root directory with the following variables:

MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=MONGO_DB_NAME

Replace the MongoDB URI with your own connection string. You can use a local MongoDB instance or a MongoDB Atlas connection string.

Configuration

MongoDB Connection

The server uses the following configuration parameters:

• MONGO_URI: MongoDB connection string (default: mongodb+srv://test.nckd7.mongodb.net/MONGO_DB_NAME)
• MONGO_DB_NAME: Name of the MongoDB database to use (default: MONGO_DB_NAME)

You can configure these parameters in three ways:

1. Environment variables (recommended for production)
2. .env file (recommended for development)
3. Default values in src/config.ts (not recommended for production)

MongoDB Connection Options

The connection options are defined in src/config.ts:

export const MONGO_OPTIONS = {
  serverSelectionTimeoutMS: 5000, // 5 seconds timeout for server selection
  connectTimeoutMS: 5000, // 5 seconds timeout for initial connection
};

Building and Running

Build the Server

npm run build

Start the Server

npm run start

Using the Start Script

For convenience, you can use the provided start script:

./start-mcp-server.sh

This script:

1. Checks if MongoDB is running locally
2. Builds the server
3. Sets environment variables for MongoDB connection
4. Starts the server

Setting Up Sample Data

The server includes sample data for testing. To set up this data:

npm run setup-enhanced

This will create the following collections with sample data:

• reviews
• inventory_transactions
• support_tickets
• shipping_locations
• analytics_events

Integrating with CopilotKit

To configure this MCP server in your CopilotKit application:

1. Open the MCP configuration modal
2. Add a new server with the following details:
   • Server Name: mongodb
   • Connection Type: stdio
   • Command: node
   • Arguments: /path/to/mongo-mcp/build/index.js

Available Tools

Basic Tools

1. create-database

   • Create a new MongoDB database with specified collections
   • Parameters: collections (array of collection names)

2. insert-data

   • Insert data into a MongoDB collection
   • Parameters: collection (collection name), data (object or array of objects)

3. query-data

   • Query data from MongoDB using natural language
   • Parameters: collection (collection name), query (natural language query), limit (optional, max results)

Enhanced Tools

4. product-reviews

   • Get product reviews with filtering and sorting options
   • Parameters: productId (optional), minRating (optional), verifiedOnly (optional), sortBy (optional), limit (optional)

5. inventory-management

   • Manage product inventory with various operations
   • Parameters: operation (check/history/update), productId, locationId (optional), quantity (optional), type (optional), notes (optional)

6. support-tickets

   • Manage customer support tickets
   • Parameters: action (list/view/create/update), ticketId (optional), userId (optional), status (optional), priority (optional), subject (optional), description (optional), category (optional), limit (optional)

7. analytics-insights

   • Get insights from analytics data
   • Parameters: insightType, timeframe (optional), productId (optional), limit (optional)

8. shipping-locations

   • Manage shipping and warehouse locations
   • Parameters: action (list/view/capacity), locationType (optional), locationCode (optional), activeOnly (optional)

Use Cases

Creating a Database and Collections

{
  "collections": ["users", "products", "orders"]
}

Inserting Data

{
  "collection": "products",
  "data": {
    "name": "Laptop",
    "price": 999.99,
    "category": "Electronics",
    "stock": 50
  }
}

Querying Data

{
  "collection": "products",
  "query": "find all laptops with price less than 1000",
  "limit": 5
}

Managing Product Reviews

{
  "productId": "Laptop",
  "minRating": 4,
  "verifiedOnly": true,
  "sortBy": "rating",
  "limit": 10
}

Checking Inventory

{
  "operation": "check",
  "productId": "Laptop"
}

Managing Support Tickets

{
  "action": "list",
  "status": "open",
  "priority": "high",
  "limit": 5
}

Getting Analytics Insights

{
  "insightType": "product_popularity",
  "timeframe": "month",
  "limit": 5
}

Managing Shipping Locations

{
  "action": "capacity",
  "locationType": "warehouse",
  "activeOnly": true
}

Troubleshooting

MongoDB Connection Issues

If you encounter connection issues:

1. Verify MongoDB is running:

   nc -z localhost 27017
   

2. Check your MongoDB URI in the .env file or environment variables

3. Ensure network connectivity to your MongoDB instance

4. Check MongoDB logs for any errors:

   sudo journalctl -u mongod
   

Server Startup Issues

If the server fails to start:

1. Check for build errors:

   npm run build
   

2. Verify Node.js version:

   node --version
   

3. Check for dependency issues:

   npm install
   

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.