Mongo

You run a MongoDB MCP Server to interact with your MongoDB data through a standardized Model Context Protocol. It enables asynchronous CRUD operations, structured error handling, and real-time updates via SSE, all while providing flexible deployment options from local development to containerized setups.

How to use

You connect an MCP client to the server to perform CRUD actions on MongoDB databases, collections, and documents. Use the provided endpoints to check health, access the MCP API, establish real-time SSE streams, and send messages to perform operations. The server handles authentication, error propagation, and supports async workflows for responsive applications.

How to install

Prerequisites include Python and a working container or runtime for local testing. Install the MCP server and run it in your preferred mode using the commands shown in the setup options.

# Development setup: clone repository and install in editable mode
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# Install in editable mode
pip install -e .

# Run the server with the default HTTP transport
mongo-mcp-server

# Run the server with SSE transport
mongo-mcp-server --transport=sse

# Specify MongoDB URL
mongo-mcp-server --mongodb-url="mongodb://username:password@hostname:port/dbname"

# Show help
mongo-mcp-server --help

# UVX-based run (if you use UVX for service management)
uvx mongo-mcp-server

# SSE transport via UVX
uvx mongo-mcp-server --transport=sse

# Python runtime (manual run)
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

pip install -r requirements.txt

export MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"
uvicorn app.main:app --host 0.0.0.0 --port 3000

# Docker Compose (dockerized deployment)
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

docker-compose up -d

docker-compose logs -f mongo-mcp

# UVX service management (example)
chmod +x uvx-register.sh
./uvx-register.sh
uvx start mongo-mcp
uvx status mongo-mcp
uvx logs mongo-mcp

Note: Use the method that fits your environment, whether you prefer a local Python run, a UVX-managed service, or a Docker installation. Ensure your MONGODB_URL is valid and reachable from the server host.

## Additional configuration and notes

Environment variables play a key role in running the MCP server. The essential variable is MONGODB\_URL, which must point to your MongoDB instance. You can also control the port and transport method with optional variables.

Key environment variables shown in usage includes:
- MONGODB\_URL: The MongoDB connection string (required).
- PORT: The listening port for the server (default 3000).
- MCP\_TRANSPORT: Transport protocol to use, either http or sse.

API endpoints you will encounter:
- GET /health for status checks
- GET /mcp for the MCP API (OpenAPI document)
- GET /sse for Server-Sent Events stream
- POST /messages to handle incoming messages for operations

## Troubleshooting and tips

If the server does not start, run with --help to verify available options and double-check that your MongoDB URL is correct. For MongoDB connection issues, ensure the URL is reachable from the server host and that authentication details are valid. When running with Docker, inspect logs using docker-compose logs or docker logs for troubleshooting.

## Security and deployment notes

When deploying to production, prefer a secure transport (HTTPS) and restrict access to the MCP endpoints as needed. Store credentials and connection strings in a secure environment manager, and rotate credentials periodically. If you enable SSE in public networks, consider access controls and network-level protections to prevent unauthorized clients from subscribing to real-time updates.

## Appendix: Tools and capabilities

The MCP server exposes a set of database interaction capabilities you can leverage from clients. These are demonstrated by typical operations such as listing collections, querying documents, inserting or updating records, deleting entries, and managing indexes. You can use these actions to implement robust data workflows in your applications.

## Available tools

### listCollections

Retrieve all available collections in the database.

### find

Query and fetch documents from a collection using MongoDB query syntax.

### insertOne

Insert a single document into a collection.

### updateOne

Update a single document in a collection.

### deleteOne

Delete a single document from a collection.

### indexes

List all indexes for a collection.

### createIndex

Create a new index on a collection.

### dropIndex

Remove an existing index from a collection.