queue-inspector-mcp

An MCP server that lets an agent inspect and operate Redis-backed job queues. It speaks to three backends today, Asynq (Go) and BullMQ (Node) and Sidekiq (Ruby): per-state counts, individual job detail, and moving jobs between states — six tools over stdio, with a --read-only mode that drops the mutating ones entirely.

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, whether a dead job can be requeued. A generic Redis MCP server shows you keys and raw values; this one understands Asynq's protobuf task messages and BullMQ's state structures, and Sidekiq's inline job JSON, so an agent can answer those questions directly.

What this looks like from the agent side. The tool output below is recorded, not mocked: a local Redis seeded with real Asynq tasks, an SMTP relay down, and one delivery out of attempts.

> smtp relay was down earlier, it's back now - did we strand anything in the default queue?

⏺ queues - queue_stats (MCP)(queue: "default")
  ⎿  { "queue": "default", "backend": "asynq", "states": { "pending": 0, "active": 0,
       "scheduled": 6, "retry": 38, "archived": 1, "completed": 57 } }

⏺ 38 tasks are stuck in retry and one is archived. Sampling the retries to see why.
⏺ queues - list_jobs (MCP)(queue: "default", state: "retry", limit: 3)
  ⎿  { …, "count": 3, "jobs": [
       { "id": "46c6ba86-…", "type": "email:deliver", …, "attempts": 5, "maxRetries": 25,
         "lastError": "dial tcp 127.0.0.1:2525: connect: connection refused" }, … ] }

⏺ Every sampled retry is email:deliver failing to reach the relay; those re-run on their own
  now that it's back. The archived task is out of attempts — it never will.
⏺ queues - list_jobs (MCP)(queue: "default", state: "archived", limit: 1)
  ⎿  { …, "count": 1, "jobs": [ { "id": "814cc556-04a8-4923-8de5-71a661c6063c", … } ] }
⏺ queues - get_job (MCP)(queue: "default", id: "814cc556-04a8-4923-8de5-71a661c6063c")
  ⎿  { …, "type": "email:deliver", "state": "archived", …, "attempts": 8, "maxRetries": 8,
       …, "fullError": "dial tcp 127.0.0.1:2525: connect: connection refused",
       "timestamps": { …, "lastFailedAt": "2026-07-10T14:01:40.000Z", … },
       "payload": "{\"to\":\"dana@example.test\",\"template\":\"receipt\"}", … }

⏺ A receipt email that burned all 8 attempts during the outage. Requeuing it.
⏺ queues - retry_job (MCP)(queue: "default", id: "814cc556-04a8-4923-8de5-71a661c6063c")
  ⎿  { "ok": true, "message": "asynq task 814cc556-04a8-4923-8de5-71a661c6063c moved to
       pending in queue \"default\"" }

⏺ queues - queue_stats (MCP)(queue: "default")
  ⎿  { "queue": "default", "backend": "asynq", "states": { "pending": 1, "active": 0,
       "scheduled": 6, "retry": 38, "archived": 0, "completed": 57 } }
⏺ The receipt is back in pending. The other 38 will re-run as their backoff timers come due.

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"]
    M --> B3["Sidekiq adapter<br/>job JSON in lists + zsets"]
    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 Redis key layout — Asynq's protobuf task messages, BullMQ's state-by-membership sorted sets, and Sidekiq's inline job JSON — instead of treating Redis as a bag of keys.

Why an MCP server instead of the CLI

Asynq ships a CLI, and redis-cli can read anything. But wiring a CLI into an agent means giving the agent a shell. The tools here return structured JSON the model can reason over rather than aligned text to re-parse; they work in clients that have no shell, like Claude Desktop; and read-only is enforced by construction — under --read-only the mutating tools are not in tools/list at all, which is a stronger guarantee than a confirmation prompt a model can talk its way past.

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", "QUEUE_INSPECTOR_READ_ONLY": "1" }
    }
  }
}

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" }
    }
  }
}

Both examples are read-only. To enable retry_job and delete_job, remove QUEUE_INSPECTOR_READ_ONLY.

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 more than one backend, 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 Redis.

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.

Compatibility