Cosmosdb

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

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint

Returns a sorted JSON array of database names.

cosmosdb_list_containers

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name

Returns a sorted JSON array of container names.

cosmosdb_get_container_info

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name

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

cosmosdb_query_items

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
query	string	yes	SQL query (e.g. SELECT * FROM c WHERE c.status = 'active')
max_items	integer	no	Max items to return (default 100, cap 1000)

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.

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
query	string	yes	SQL query
output_file	string	yes	Path to write results as a JSON array
max_items	integer	no	Max items to return (default 100, cap 1000)

cosmosdb_count_items

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
where	string	no	SQL WHERE clause body (e.g. c.status = 'active'). If omitted, counts all items.

Returns a JSON object with a count field.

cosmosdb_read_item

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
item_id	string	yes	Item id field value
partition_key	string	yes	Partition key value

Returns the full item document as JSON.

cosmosdb_upsert_item

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
item	object	yes	Full item document — must include an id field

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

cosmosdb_delete_item

Destructive. Deletes an item permanently.

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
container	string	yes	Container name
item_id	string	yes	Item id field value
partition_key	string	yes	Partition key value

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.