MCP CosmosDB - Azure CosmosDB

You can run and manage CosmosDB operations through an MCP server that exposes powerful, secure data access and management tools. This server supports multiple CosmosDB accounts, provides read operations by default, and allows write operations only when explicitly enabled per connection, making it suitable for safe data exploration and controlled CRUD activities.

How to use

You will run an MCP server instance and connect your MCP client to it. Start by choosing a connection configuration method that fits your deployment: external file with multiple connections, inline JSON definitions, or a single legacy connection. You can then use the available tools to list databases, inspect containers, run SQL-like queries, and perform CRUD actions when allowed.

How to install

Prerequisites you need before installing are Node.js 18+ and npm. Ensure you have an Azure CosmosDB account and a connection string ready if you plan to run write operations.

Follow these concrete steps to set up and run the MCP CosmosDB server configurations shown in the examples.

# 1) Install dependencies and build if needed (local development path)
git clone https://github.com/hendrickcastro/MCPCosmosDB.git
cd MCPCosmosDB
npm install
npm run build

# 2) Run in development mode (example stdio config using a built dist path)
node dist/server.js

Configuration and security

The server supports three configuration methods, prioritized from highest to lowest. External JSON file, inline JSON string, and a legacy single connection. By default, write operations are disabled for safety and can be enabled per connection.

Security configuration for write access is controlled via the allowModifications flag in the connection definitions or via a global environment variable when using a single connection.

Usage examples

Here are representative usage patterns you can follow once the server is running and your client is connected.

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
      }
    }
  }
}

Alternatively, you can inline the connections as a JSON string or run a local development flow that builds and starts the server with a direct path to the built artifact.

Troubleshooting

If you encounter connection issues, verify the connection string format includes AccountEndpoint and AccountKey, confirm the databaseId matches an existing database, and adjust network settings if timeouts occur.

If write operations are blocked, ensure allowModifications is true for the relevant connection, or set DB_ALLOW_MODIFICATIONS=true in a single-connection scenario.

Notes on best practices

Always use TOP N and specify fields in queries to minimize RU consumption. Partition keys should be provided for single-partition operations to improve performance. Monitor request charges and keep connection strings secure, preferably via an external file.

Development and architecture

The project is built with a modular structure that caches connections, supports multiple connections, and provides robust error handling and telemetry. The server exposes a suite of 13 tools for document database analysis, querying, and CRUD operations.

Contact and licensing

This server is available under the MIT License. It integrates with the Model Context Protocol SDK and uses the Azure CosmosDB SDK under the hood to interact with CosmosDB resources.

Available tools

mcp_list_connections

List all configured connections with their status

mcp_list_databases

List all databases in the connected CosmosDB account

mcp_list_containers

List all containers in the current database

mcp_get_container_definition

Get detailed container configuration including partition key and indexing policy

mcp_get_container_stats

Get container statistics such as document count and size

mcp_cosmos_query

Execute SQL-like queries with optional parameters and performance metrics

mcp_get_documents

Retrieve documents with optional filtering and sorting

mcp_get_document_by_id

Retrieve a single document by its ID and partition key

mcp_analyze_schema

Analyze and summarize the document schema within a container

mcp_create_document

Create a new document in a container (requires modifications enabled)

mcp_update_document

Update/replace an existing document (requires modifications enabled)

mcp_delete_document

Delete a document from a container (requires modifications enabled)

mcp_upsert_document

Create or update a document (requires modifications enabled)