mongodb

This MCP server provides read-only access to a MongoDB instance. It exposes two main tools: aggregate and explain. The aggregate tool runs MongoDB aggregation pipelines against a connected database and returns results, with a default limit of 1000 documents if the pipeline does not include a limit stage, and a default operation timeout of 30 seconds. The explain tool returns execution plans for given aggregation pipelines, with verbosity levels such as queryPlanner, executionStats, or allPlansExecution. In addition, the server can supply inferred collection schemas by sampling documents from each collection, exposed at collection/schema endpoints to help you understand data types without querying raw data directly. To connect, you supply a MongoDB URI via environment variable MONGODB_URI (e.g., mongodb+srv://<username>:<password>@cluster0.mongodb.net). You can use these tools from clients like Claude Desktop by configuring an MCP server entry that points to this package via npx (as shown in the example configuration).

Example usage in Claude Desktop or equivalent MCP clients:

• aggregate: Provide collection, pipeline array, and optional options (allowDiskUse, maxTimeMS, comment). The server will execute the pipeline and return results up to 1000 docs by default, respecting the 30-second timeout unless overridden by maxTimeMS.
• explain: Provide collection, pipeline, and desired verbosity. The response contains a MongoDB query plan or detailed execution statistics depending on verbosity.
• Collection schemas: Access endpoints like mongodb://<host>/<collection>/schema to retrieve inferred JSON schemas for fields and types based on sampled documents.

Prerequisites

• Node.js (version 18+ recommended) and npm installed on your machine
• Access to a MongoDB instance (cluster or local) with a URI you can provide via MONGODB_URI

Installation steps

1. Prereq check

• Verify Node.js and npm are installed:

node -v
npm -v

2. Install or use via npx

• You can run the MCP server directly with npx (no local install required):

# Ensure npm is up to date, then run the server via npx
npm i -g npm
npx -y @pash1986/mcp-server-mongodb

• Alternatively, install locally or globally (optional):

# Local install (in your project folder)
npm init -y
npm install @pash1986/mcp-server-mongodb

3. Configure environment for MongoDB connection

• Set the MongoDB URI in your environment before starting the server:

export MONGODB_URI="mongodb+srv://<username>:<password>@cluster0.mongodb.net"

4. Run with the recommended configuration

• If using Claude Desktop or another MCP client, configure the server to run via npx as shown in the mcp_config example. If running manually, start the package (the exact command may vary slightly depending on how you invoke it) and ensure the MONGODB_URI environment variable is present.

# Example run (npx usage as per configuration):
npx -y @pash1986/mcp-server-mongodb

Tips and common issues:

• Ensure the MONGODB_URI is correctly formatted and reachable from the host running the MCP server. Network access and proper credentials are required.
• The server is read-only by design; the tools provided (aggregate, explain) do not modify data.
• If you encounter timeouts, consider increasing maxTimeMS in your pipeline or adjusting the server timeout settings in your client configuration.
• Schema inference is based on sampling; schemas are represented as inferred JSON structures and may not capture all edge cases for every document.
• When using Claude Desktop, the example configuration shows how to wire the server into the mcpServers section; you can adapt the env and URI values to your environment.