MCP Server

bunqueue ships a Model Context Protocol server, bunqueue-mcp, that lets an AI agent (Claude Desktop, Claude Code) drive the queue with tools, resources, and prompts.

External MCP mutations bypass dashboard safety gates

The upstream v2.9.3 MCP tool set includes Cancel, Discard, Drain, Obliterate, DLQ Retry and DLQ Purge. Those tools do not gain atomic generation/state/topology or reverse-dependency checks merely because an MCP client invokes them. The dashboard's own Copilot exposes only Promote, Pause and Resume mutations; its DLQ retry tool is absent. Grant the external MCP server write access only when you have independently established that flow topology cannot be stranded and that job-ID reuse cannot retarget the action.

It is a separate stdio process, launched by the MCP client rather than by this dashboard, and it is not part of the HTTP API on :6790. That is why the dashboard's MCP page (and this guide) is a setup and reference, not a live monitor. The server needs the optional peer dependency @modelcontextprotocol/sdk.

Install the runtime

Install Bunqueue and its optional SDK in a dedicated directory:

mkdir bunqueue-mcp-runtime
cd bunqueue-mcp-runtime
bun add --exact bunqueue@2.9.4 @modelcontextprotocol/sdk@1.30.0

Replace /absolute/path/bunqueue-mcp-runtime below with that directory's absolute path. bun must be on the MCP client's PATH. Installing both packages explicitly avoids depending on an optional peer being supplied by a transient bunx cache. The dashboard's local regression uses this public executable over stdio and the real authenticated TCP broker.

Connection modes

Embedded (default)

Direct SQLite access, with no running server. Point DATA_PATH at the bunqueue database file. Best for a local agent on the same machine.

{
  "mcpServers": {
    "bunqueue": {
      "command": "bun",
      "args": ["/absolute/path/bunqueue-mcp-runtime/node_modules/.bin/bunqueue-mcp"],
      "env": { "DATA_PATH": "./data/bunq.db" }
    }
  }
}

TCP (remote server)

Connect to a running bunqueue server over its TCP protocol port (6789, distinct from the HTTP admin API on 6790). Use BUNQUEUE_TOKEN if the server has one.

{
  "mcpServers": {
    "bunqueue": {
      "command": "bun",
      "args": ["/absolute/path/bunqueue-mcp-runtime/node_modules/.bin/bunqueue-mcp"],
      "env": {
        "BUNQUEUE_MODE": "tcp",
        "BUNQUEUE_HOST": "localhost",
        "BUNQUEUE_PORT": "6789",
        "BUNQUEUE_TOKEN": "your-token"
      }
    }
  }
}

Where to put it

For Claude Desktop, add the JSON above to claude_desktop_config.json. For Claude Code, register it from the CLI:

claude mcp add bunqueue -- bun /absolute/path/bunqueue-mcp-runtime/node_modules/.bin/bunqueue-mcp

What it exposes

Tools (73, in 12 categories)

Every tool name is prefixed bunqueue_; the examples below drop the prefix.

Category	Count	Examples
Jobs	11	add_job, get_job, get_jobs, get_job_result, wait_for_job
Job management	6	cancel_job, change_job_priority, promote_job, update_job_data
Consumption	8	pull_job, pull_job_batch, ack_job, fail_job, job_heartbeat
Queues	11	list_queues, pause_queue, resume_queue, drain_queue, obliterate_queue
Dead letter queue	4	get_dlq, retry_dlq, purge_dlq
Cron	4	add_cron, list_crons, get_cron, delete_cron
Flows	4	add_flow, add_flow_chain, get_flow, get_children_values
Rate limits	4	set_rate_limit, set_concurrency, clear_rate_limit
Webhooks	4	add_webhook, list_webhooks, remove_webhook, set_webhook_enabled
Workers	3	register_worker, unregister_worker, worker_heartbeat
Handlers	3	register_handler, list_handlers, unregister_handler
Monitoring	11	get_stats, get_queue_stats, get_memory_stats, get_prometheus_metrics

Resources (5)

bunqueue://queues, bunqueue://stats, bunqueue://workers, bunqueue://crons, bunqueue://webhooks.

Prompts (3)

bunqueue_debug_queue, bunqueue_health_report, bunqueue_incident_response.

Verified TCP worker limitation

With Bunqueue 2.9.4, register_worker can return success: true with worker ID "0", while the broker registry contains a different real ID. A heartbeat using "0" returns success: false. Read list_workers, match a unique worker name and its queues, and use that actual ID for heartbeat and unregister. Check the tool's JSON success field as well as MCP's isError flag.

The regression verifies registration, the real registry ID, a successful heartbeat, display in the dashboard and removal. It also reads the stats resource and health-report prompt. This is not a test of every external MCP mutation.