Azure Service Bus MCP Server

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

Exposes tools for sending messages, inspecting queue and subscription contents, and purging test data. The built-in Azure MCP server that ships with Claude Code only supports read operations (queue details, message counts, etc.) and cannot send messages — this project fills that gap.

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

Requirements

• uv

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

• Your identity must have the Azure Service Bus Data Owner or Azure Service Bus Data Receiver/Sender roles on the target namespace

Installation

Install uv if you don't have it:

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-service-bus -- uvx servicebus-mcp

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

{
  "mcpServers": {
    "azure-service-bus": {
      "command": "uvx",
      "args": ["servicebus-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 servicebus_list_namespaces if set

• AZURE_SERVICEBUS_CONNECTION_STRING — use instead of az login for data plane operations (send, peek, purge)

Installing from source

If you prefer to run from a local clone:

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

Then configure with the cloned path:

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

Restart your MCP client after adding the server.

Tools

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

servicebus_list_namespaces

List all Service Bus namespaces 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.

servicebus_list_queues

List all queues in a Service Bus namespace.

Returns a sorted JSON array of queue names.

servicebus_list_topics

List all topics in a Service Bus namespace.

servicebus_send_message

Send a single message to a queue or topic.

Returns a success message confirming the message was sent or scheduled.

servicebus_send_batch

Send multiple messages in a single batch. Useful for seeding test data.

servicebus_peek_messages

Non-destructively peek at messages in a queue. Messages are not locked or consumed.

Returns message bodies and metadata (sequence number, enqueue time, properties). Use servicebus_peek_messages_to_file instead if message bodies may be large.

servicebus_peek_messages_to_file

Same as servicebus_peek_messages but writes message bodies to a file. Only metadata is returned in context, avoiding large payloads filling the context window.

servicebus_peek_dlq

Non-destructively peek at messages in a queue's dead letter queue.

Returns message bodies, dead letter reason, error description, and other metadata.

servicebus_peek_dlq_to_file

Same as servicebus_peek_dlq but writes message bodies to a file.

servicebus_purge_queue

Delete all messages from a queue. This is destructive and cannot be undone.

servicebus_purge_dlq

Delete all messages from a queue's dead letter queue. This is destructive and cannot be undone.

servicebus_requeue_dlq

Move messages from a queue's dead letter queue back to the main queue. Preserves body, session ID, correlation ID, and application properties.

servicebus_peek_subscription_messages

Non-destructively peek at messages in a topic subscription.

servicebus_peek_subscription_messages_to_file

Same as servicebus_peek_subscription_messages but writes message bodies to a file.

servicebus_peek_subscription_dlq

Non-destructively peek at messages in a topic subscription's dead letter queue.

servicebus_peek_subscription_dlq_to_file

Same as servicebus_peek_subscription_dlq but writes message bodies to a file.

servicebus_purge_subscription

Delete all messages from a topic subscription. This is destructive and cannot be undone.

servicebus_purge_subscription_dlq

Delete all messages from a topic subscription's dead letter queue. This is destructive and cannot be undone.

servicebus_requeue_subscription_dlq

Move messages from a topic subscription's dead letter queue back to the topic. Preserves body, session ID, correlation ID, and application properties.

Security

• This server only accepts DefaultAzureCredential — connection strings and SAS keys are never passed as arguments, ensuring secrets do not appear in conversation history.

• purge_* and requeue_* tools enforce a max_messages safety cap to prevent accidental bulk operations on large backlogs.