Cabal Town MCP Server

A MongoDB Context Protocol (MCP) server for use with Cursor IDE, allowing AI agents to connect to and query your MongoDB databases securely using the Model Context Protocol.

What is MCP?

MCP (Model Context Protocol) provides a standardized way for AI agents to interact with external systems and data sources. This package specifically enables AI agents in Cursor IDE to connect to your MongoDB database in a controlled, secure manner.

Installation and Usage

You can run this MCP server directly with npx without installing it globally:

npx cabal-town-mcp-server

Or install it globally:

npm install -g cabal-town-mcp-server
cabal-mcp

This will start the MCP server with default settings. By default, it connects to a MongoDB instance at mongodb://localhost:27017/cabal-town-db.

Quick Start

The simplest way to use this server is to provide just the MongoDB connection URL:

MONGODB_URI=mongodb+srv://username:password@host/database?options npx cabal-town-mcp-server

The server will automatically extract the database name from the URL. If your URL contains a placeholder like %DATABASE%, it will be replaced with cabal-town-db.

Configuration Options

There are several ways to configure the MCP server:

1. Using Environment Variables

# The only required variable - MongoDB connection string (either MONGODB_URI or MONGODB_URL)
MONGODB_URI=mongodb+srv://username:password@host/database?options \
# Optional settings
MCP_ALLOWED_COLLECTIONS=users,products,orders \
npx cabal-town-mcp-server

2. Using a .env File

Create a .env file in your project directory:

# MongoDB Connection
MONGODB_URI=mongodb://localhost:27017/cabal-town-db

# Security settings
MCP_ALLOWED_COLLECTIONS=users,documents,products,orders

Then run:

npx cabal-town-mcp-server

Available Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MONGODB_URI or MONGODB_URL | MongoDB connection string (required) | mongodb://localhost:27017/cabal-town-db | | DB_NAME | Database name (optional, extracted from URI if not provided) | Extracted from URI | | MCP_ALLOWED_COLLECTIONS | Comma-separated list of allowed collections | users,documents,products,orders |

MCP Tools

This server provides the following MCP tools that Cursor can use to interact with your MongoDB database:

1. Aggregate Tool

Runs MongoDB aggregation pipelines against your collections.

Example:

aggregate({
  collection: "users",
  pipeline: [
    { $match: { status: "active" } },
    { $sort: { lastLogin: -1 } },
    { $limit: 5 }
  ]
})

2. Explain Tool

Analyzes MongoDB query execution plans to help with optimization.

Example:

explain({
  collection: "orders",
  pipeline: [{ $match: { status: "pending" } }],
  verbosity: "executionStats"
})

3. Sample Tool

Gets random sample documents from a collection.

Example:

sample({
  collection: "products",
  count: 3
})

Security Features

This MCP server includes several security features:

1. Collection Access Control: Only collections defined in the MCP_ALLOWED_COLLECTIONS environment variable can be accessed.
2. Field Masking: Sensitive fields like passwords and tokens are automatically masked in responses.
3. Input Validation: All inputs are validated before being sent to the database.

Using with Cursor IDE AI

In Cursor IDE, you can reference your MCP server in your AI conversations:

Please analyze my MongoDB database. I have an MCP server running locally.

Version History

• 1.0.4 - Current version with MCP standard implementation
• 1.0.3 - Initial public release

License

ISC