Azure Cosmos DB MCP Server

An MCP (Model Context Protocol) server for Azure Cosmos DB. Compatible with any MCP client — Claude Code, Claude Desktop, Cursor, and others.

Exposes tools for listing accounts, databases, and containers, running SQL queries, reading and writing documents, and deleting items. The built-in Azure MCP server that ships with Claude Code provides limited Cosmos DB support — this project covers the full data plane, including writes.

Authentication uses DefaultAzureCredential, which picks up an active az login session automatically. Alternatively, a key can be provided via the AZURE_COSMOS_KEY environment variable. No secrets or keys are ever passed as tool arguments.

Requirements

• uv

• Azure CLI with an active az login session, or AZURE_COSMOS_KEY set in your environment

Installation

Install uv and the Azure CLI if you don't have them:

macOS

brew install uv azure-cli

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash   # Debian/Ubuntu

For other Linux distributions see the Azure CLI install docs.

Windows

winget install --id=astral-sh.uv
winget install --id=Microsoft.AzureCLI

Configuration

Claude Code users:

claude mcp add --scope user cosmosdb -- uvx cosmosdb-mcp

For other MCP clients, add the following to your server configuration:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "uvx",
      "args": ["cosmosdb-mcp"]
    }
  }
}

Restart your MCP client after adding the server. No environment variables are required if you are authenticated with az login. Optional env vars:

• AZURE_SUBSCRIPTION_ID — used by cosmosdb_list_accounts if set

• AZURE_COSMOS_KEY — use instead of az login for data plane operations

Installing from source

git clone https://github.com/BrianDeacon/cosmosdb-mcp
cd cosmosdb-mcp
uv sync
az login

Then configure with the cloned path:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/cosmosdb-mcp", "cosmosdb-mcp"]
    }
  }
}

Tools

The account parameter accepts either a short account name (e.g. my-cosmos-account) or a full endpoint URL (e.g. https://my-cosmos-account.documents.azure.com). The prefix and suffix are added automatically if absent.

cosmosdb_list_accounts

List all Cosmos DB accounts in the current Azure subscription. The subscription is resolved automatically — first from the AZURE_SUBSCRIPTION_ID environment variable, then from the active az login session.

cosmosdb_list_databases

Returns a sorted JSON array of database names.

cosmosdb_list_containers

Returns a sorted JSON array of container names.

cosmosdb_get_container_info

Returns partition key path, indexing policy, default TTL, unique key policy, and system properties.

cosmosdb_query_items

Cross-partition queries are enabled automatically. Use cosmosdb_query_items_to_file instead if the result set may be large.

cosmosdb_query_items_to_file

Same as cosmosdb_query_items but writes results to a file. Only the item count is returned in context, avoiding large payloads filling the context window.

cosmosdb_count_items

Returns a JSON object with a count field.

cosmosdb_read_item

Returns the full item document as JSON.

cosmosdb_upsert_item

Inserts or replaces the item. Returns the stored document including system fields.

cosmosdb_delete_item

Destructive. Deletes an item permanently.

Security

• Authentication relies on DefaultAzureCredential or AZURE_COSMOS_KEY — keys are never passed as tool arguments, so secrets do not appear in conversation history.

• The account parameter only accepts account names and endpoint URLs, never connection strings.