Bussin MCP

bussin-mcp

Azure Service Bus tools for Claude, ChatGPT, Cursor, and any other MCP-aware client.

A Model Context Protocol server that lets an AI assistant inspect your Azure Service Bus queues, topics, subscriptions and dead-letter queues. Peek messages, search payloads and replay failures, using the same AMQP client that powers the Bussin web explorer.

Read-only by default. Nothing writes to your broker unless you say so.

npx -y bussin-mcp --demo

Install

npm install -g bussin-mcp

Or run it straight from npx, which is what the client config below does.

Quick start

Try it with no Azure account at all. --demo runs against an in-process simulator with seeded queues:

npx -y bussin-mcp --demo

Claude Code

claude mcp add bussin -- npx -y bussin-mcp --namespace my-namespace

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json, or .cursor/mcp.json):

{

"mcpServers": { "bussin": { "command": "npx", "args": ["-y", "bussin-mcp", "--namespace", "my-namespace"] } } }

Authentication

Entra ID is the default and the recommended path. The server uses Azure's DefaultAzureCredential, so it picks up whatever you already have:

az login

That also works with managed identity, or a service principal via AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET.

You need two role assignments on the namespace (or its resource group):

A SAS connection string is supported for namespaces your signed-in identity cannot see:

npx -y bussin-mcp --connection-string "Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=..."

Connection strings authenticate the data plane only. Entity discovery (list_queues and friends) goes through Azure Resource Manager and needs Entra ID.

Safety model

The caller is a language model, so anything irreversible is opt-in. Tools you have not enabled are not registered at all: they are invisible to the model rather than merely refused, so there is nothing to talk it into.

Additional guards:

• Peek is genuinely non-destructive: no lock, no consumption, no delivery-count bump.
• `purge_entity` requires confirmation: the confirm argument must exactly equal the entity name being purged.
• `resubmit_dead_letter` is additive by default: it copies messages back to the source queue and leaves the dead-lettered originals in place. Removing them additionally requires --allow-destructive.
• Scans are bounded: searches and purges stop at --search-timeout-ms (default 30s) rather than hanging the call.
• Message bodies are truncated at 4000 characters per message, so a fat payload cannot blow out the model's context.

Options

Tools

Always available

• `list_namespaces`: every Service Bus namespace the identity can see, across subscriptions
• `list_queues`: queues with active, dead-letter and scheduled counts
• `list_topics`: topics with message counts
• `list_subscriptions`: subscriptions under a topic, with counts
• `peek_messages`: read messages from a queue, subscription, or dead-letter queue
• `search_messages`: scan for a body substring, message id, or subject

With --allow-send

• `send_message`: send to a queue or topic
• `resubmit_dead_letter`: replay dead-lettered messages back to their source queue

With --allow-destructive

• `delete_messages`: permanently delete specific messages by sequence number
• `dead_letter_messages`: move active messages to the dead-letter queue

Service Bus only receives deferred messages by sequence number, so both tools lock messages from the head of the queue up to the requested ones, settle those and release the rest. Their result lists what was settled and, under notFound, any sequence numbers that weren't.

• `purge_entity`: delete every message from a queue, subscription, or DLQ

Example prompts

Which queues in my-namespace have dead-lettered messages?

Show me the last 5 dead-lettered messages on the orders queue and tell me what they have in common.

Search the payments subscription for anything mentioning "timeout" in the last batch.

These three DLQ messages failed on a bug we've now fixed, so resubmit them.

Related

• Bussin: the browser-native Azure Service Bus explorer this is built from
• app.bussin.dev: the web app, no install required
• github.com/sgebb/bussin: source

Development

npm install

npm run build # builds the Node bundle of bussin-client-js, then bundles with esbuild npm test # drives the server over stdio against the simulator npm run typecheck # tsc --noEmit

bussin-client-js lives in this repo and is inlined at build time, so the published package is self-contained and has no file: dependency.

Releasing

Publishing is driven by a tag, so it is always deliberate:

1. Bump version in package.json
2. Add the release to the changelog
3. Tag and push:

git tag mcp-v0.1.0 && git push origin mcp-v0.1.0

The workflow refuses to publish if the tag and package.json versions disagree, or if that version is already on npm. It publishes with --provenance, which links the tarball to the workflow run and commit that produced it.

One-time setup: create an npm automation token with publish rights, add it as the NPM_TOKEN secret under a repository environment named npm-publish.

To validate without publishing, run the workflow manually with dry_run enabled.

License

Business Source License 1.1 (BUSL-1.1) — see LICENSE.

Free for personal, educational, and internal business use. Commercial redistribution, rebranding, or hosting this software as a service by third parties is prohibited. Converts to Apache 2.0 on 2029-01-01.