# 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](https://docs.astral.sh/uv/)
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-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

```bash
brew install uv azure-cli
```

### Linux

```bash
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](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux).

### Windows

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

## Configuration

**Claude Code** users:

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

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

```json
{
  "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

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

Then configure with the cloned path:

```json
{
  "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.