queue-inspector-mcp

An MCP server that lets an agent inspect and operate Redis-backed job queues. It speaks to two backends today, Asynq (Go) and BullMQ (Node), reporting per-state counts, individual job detail, and moving jobs between states.

Background: I wrote up the design decisions behind this — why jobs, not keys, and the read-only posture — on my blog.

Architecture

---
config:
  look: handDrawn
---
flowchart LR
    A["AI agent"] -->|"MCP · stdio"| M["queue-inspector-mcp"]
    M --> B1["Asynq adapter<br/>protobuf msg"]
    M --> B2["BullMQ adapter<br/>state by zset"]
    B1 -->|ioredis| R[("Redis")]
    B2 -->|ioredis| R
    M -.->|"--read-only<br/>drops mutating tools"| G{{"prod-safe"}}

The server speaks MCP over stdio to the agent and talks to Redis through per-backend adapters that understand each library's on-disk layout — Asynq's protobuf task messages and BullMQ's state-by-membership sorted sets — instead of treating Redis as a bag of keys.

Related MCP server: A2AMCP

Why

When a queue misbehaves in production, the useful questions are about jobs, not keys: how many tasks are stuck in retry, what error a specific job failed with, how many attempts it has left, whether a dead job can be requeued. A plain Redis MCP server can only show you keys and raw values; it does not know that an Asynq task message is protobuf, that a BullMQ job's state is decided by which sorted set it sits in, or how either library moves a job back to the front of the line. This server encodes that knowledge so an agent can reason about queue state and take safe, state-aware actions.

Install

Requires Node.js 18 or newer and a reachable Redis.

npm install -g queue-inspector-mcp
# or run without installing:
npx queue-inspector-mcp

Configure

The server talks MCP over stdio, so it works with any MCP client. Point your client at the queue-inspector-mcp binary and set REDIS_URL.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "queues": {
      "command": "npx",
      "args": ["-y", "queue-inspector-mcp"],
      "env": { "REDIS_URL": "redis://localhost:6379" }
    }
  }
}

Claude Code (project .mcp.json, or claude mcp add):

{
  "mcpServers": {
    "queues": {
      "command": "npx",
      "args": ["-y", "queue-inspector-mcp"],
      "env": { "REDIS_URL": "redis://localhost:6379", "QUEUE_INSPECTOR_READ_ONLY": "1" }
    }
  }
}

Configuration

Tools

When a queue name is unique across the enabled backends, the backend argument is optional; the server resolves it. If the same name exists in both backends, pass backend explicitly.

Read-only mode

With --read-only or QUEUE_INSPECTOR_READ_ONLY=1, the server never registers retry_job or delete_job. The mutating tools are absent from tools/list entirely, so a client cannot call them by mistake. This is the recommended configuration for pointing an agent at a production database.

Backend state names

The two libraries model job lifecycles differently, so this server does not invent a shared vocabulary. It reports each backend's own state names, and each state maps to a specific Redis structure.

A job moves through these states over its lifetime (Asynq shown):

---
config:
  look: handDrawn
---
stateDiagram-v2
    [*] --> pending: enqueue
    pending --> active: worker picks up
    active --> completed: success
    active --> retry: handler error
    retry --> active: backoff elapsed
    retry --> archived: retries exhausted
    archived --> pending: retry_job
    completed --> [*]

Asynq:

BullMQ:

Asynq's archived is what most people mean by a "dead" job. list_jobs returns Asynq's terminal sets in Redis (score) order and BullMQ's completed/failed sets most-recent-first.

What this doesn't do

• Only Asynq and BullMQ are supported. Sidekiq, Celery, RQ and others are not.

• No web UI. This is an MCP server for programmatic use; it is not a dashboard.

• No streaming or watch. Each tool call is a point-in-time read; there is no subscription to queue events.

• retry_job and delete_job faithfully replicate each library's own mechanism rather than reimplementing it. Retry runs Asynq's Inspector.RunTask script and BullMQ's Job.retry (reprocessJob) script; delete runs Asynq's Inspector.DeleteTask script and BullMQ's Job.remove (removeJob) script. As a result the semantics match the libraries: retrying a BullMQ job applies only to failed/completed jobs and does not reset attemptsMade (matching Job.retry()); neither backend can retry or delete an active job.

• delete_job removes a single BullMQ job and does not cascade into a flow's children.

• Asynq group aggregation (the aggregating state) is not surfaced in this release.

License

MIT © Yusuf İhsan Görgel