Azure Utils

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

Covers three areas:

• Cosmos DB — list accounts, databases, and containers; run SQL queries; read, write, and delete documents
• Service Bus — list namespaces, queues, and topics; send messages; peek, purge, and requeue dead letter queues
• Authorization / PIM — list eligible roles and activate PIM role assignments

Authentication uses DefaultAzureCredential, which picks up an active az login session automatically. Optionally, Cosmos DB key-based auth and Service Bus connection-string auth can be used via environment variables (see Authentication below).

Requirements

• uv
• Azure CLI with an active az login session

Installation

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 azure-utils -- uvx azure-utils-mcp

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

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

Restart your MCP client after adding the server.

Installing from source

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

Then configure with the cloned path:

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

---

Authentication

All tools default to DefaultAzureCredential, which picks up an active az login session, managed identity, or other standard Azure credential sources.

For Cosmos DB and Service Bus, you can optionally use key-based or connection-string auth by setting environment variables. Each tool accepts an optional parameter to specify which env var to read from, with sensible defaults:

Service	Tool parameter	Default env var	What it holds
Cosmos DB	key_env_var	AZURE_COSMOS_KEY	Account key for data-plane operations
Service Bus	connection_string_env_var	AZURE_SERVICEBUS_CONNECTION_STRING	Connection string for data-plane operations

If the specified environment variable is set, its value is used for authentication. If not, DefaultAzureCredential is used as a fallback.

This design lets you point different tool calls at different credentials by overriding the env var name. For example, you might use MY_DEV_COSMOS_KEY for one account and MY_PROD_COSMOS_KEY for another, keeping both in your environment without conflict.

Other environment variables:

• AZURE_SUBSCRIPTION_ID — used by list_accounts / list_namespaces if set; otherwise resolved from az login

---

Cosmos DB Tools

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

All Cosmos DB data-plane tools (everything except cosmosdb_list_accounts) accept an optional key_env_var parameter (default AZURE_COSMOS_KEY). See Authentication.

cosmosdb_list_accounts

List all Cosmos DB accounts in the current Azure subscription.

cosmosdb_list_databases

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

cosmosdb_list_containers

Parameter	Type	Required	Description
account	string	yes	Cosmos DB account name or endpoint
database	string	yes	Database name
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

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
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

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)
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

cosmosdb_query_items_to_file

Same as cosmosdb_query_items but writes results to a file. Use when result sets may be large.

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)
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

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.
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

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
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

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
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

cosmosdb_delete_item

Destructive.

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
key_env_var	string	no	Env var holding the account key (default AZURE_COSMOS_KEY)

---

Service Bus Tools

The namespace parameter accepts either a short name (e.g. my-namespace) or a fully qualified hostname. The .servicebus.windows.net suffix is appended automatically if absent.

All Service Bus data-plane tools (everything except servicebus_list_namespaces) accept an optional connection_string_env_var parameter (default AZURE_SERVICEBUS_CONNECTION_STRING). See Authentication.

servicebus_list_namespaces

List all Service Bus namespaces in the current Azure subscription.

servicebus_list_queues

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_list_topics

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
include_subscriptions	boolean	no	If true, returns a map of topic → subscription names (default false)
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_send_message

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue or topic name
body	string	yes	Message body
session_id	string	no	Required for session-enabled queues
correlation_id	string	no	Correlation ID
application_properties	object	no	Key/value map of custom properties
scheduled_enqueue_time	string	no	ISO 8601 datetime to enqueue the message
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_send_batch

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue or topic name
messages	array	yes	Array of message objects, each with body (required), plus optional session_id, correlation_id, application_properties, scheduled_enqueue_time
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_peek_messages / servicebus_peek_messages_to_file

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue name
max_count	integer	no	Max messages (default 10, cap 100)
session_id	string	no	Peek within a specific session
output_file	string	yes (to_file only)	Path to write message bodies
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_peek_dlq / servicebus_peek_dlq_to_file

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue name
max_count	integer	no	Max messages (default 10, cap 100)
output_file	string	yes (to_file only)	Path to write message bodies
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_purge_queue / servicebus_purge_dlq

Destructive.

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue name
max_messages	integer	no	Safety cap (default 1000)
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_requeue_dlq

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
queue	string	yes	Queue name
max_messages	integer	no	Safety cap (default 100)
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_peek_subscription_messages / servicebus_peek_subscription_messages_to_file

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
topic	string	yes	Topic name
subscription	string	yes	Subscription name
max_count	integer	no	Max messages (default 10, cap 100)
session_id	string	no	Peek within a specific session
output_file	string	yes (to_file only)	Path to write message bodies
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_peek_subscription_dlq / servicebus_peek_subscription_dlq_to_file

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
topic	string	yes	Topic name
subscription	string	yes	Subscription name
max_count	integer	no	Max messages (default 10, cap 100)
output_file	string	yes (to_file only)	Path to write message bodies
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_purge_subscription / servicebus_purge_subscription_dlq

Destructive.

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
topic	string	yes	Topic name
subscription	string	yes	Subscription name
max_messages	integer	no	Safety cap (default 1000)
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

servicebus_requeue_subscription_dlq

Parameter	Type	Required	Description
namespace	string	yes	Service Bus namespace
topic	string	yes	Topic name
subscription	string	yes	Subscription name
max_messages	integer	no	Safety cap (default 100)
connection_string_env_var	string	no	Env var holding the connection string (default AZURE_SERVICEBUS_CONNECTION_STRING)

---

Authorization / PIM Tools

authorization_list_eligible_roles

List all Azure PIM roles you are eligible to activate, across all accessible subscriptions. Returns role name, scope, and whether the eligibility is permanent or time-limited.

authorization_activate_role

Parameter	Type	Required	Description
role	string	yes	Role name as returned by authorization_list_eligible_roles
scope	string	yes	Scope as returned by authorization_list_eligible_roles
justification	string	yes	Reason for activation
duration	string	no	ISO 8601 duration (e.g. PT4H). Defaults to the policy maximum.

Returns activation status and request ID. Provisioned means immediately active; PendingApproval means an approver must act first.

---

Security

• Authentication defaults to DefaultAzureCredential. When key-based or connection-string auth is used via environment variables, only the env var name is passed as a tool argument, never the secret value itself.
• purge_* and requeue_* tools enforce a max_messages safety cap to prevent accidental bulk operations.
• cosmosdb_delete_item is a hard point-delete requiring both item ID and partition key.