Yusufihsangorgel/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.
> **Background:** I wrote up the design decisions behind this — why jobs, not keys, and the read-only posture — on my blog.
Architecture
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.
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):
Claude Code (project .mcp.json, or claude mcp add):
Both examples are read-only. To enable retry_job and delete_job, remove
QUEUE_INSPECTOR_READ_ONLY.
Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| REDIS_URL | redis://localhost:6379 | Redis connection string. Include a database number, e.g. redis://localhost:6379/2. |
| ASYNQ_PREFIX | asynq | Key prefix Asynq was configured with. |
| BULL_PREFIX | bull | Key prefix BullMQ was configured with. |
| SIDEKIQ_PREFIX | (none) | Key prefix Sidekiq was configured with, if namespaced. |
| QUEUE_INSPECTOR_BACKENDS | asynq,bullmq,sidekiq | Restrict which backends are scanned. |
| QUEUE_INSPECTOR_READ_ONLY | unset | Set to 1 (or pass --read-only) to omit the mutating tools. |
Tools
| Tool | Mutating | Behavior |
| --- | --- | --- |
| list_queues | no | List every detected queue, tagged with its backend. |
| queue_stats | no | Count jobs per state for a queue, using the backend's own state names. |
| list_jobs | no | Page through jobs in one state; returns id, type, attempts, and a truncated last error. |
| get_job | no | Full detail for one job: payload, attempts, retry ceiling, last error, timestamps. |
| retry_job | yes | Move a failed or dead job back to pending/wait so it runs again. |
| delete_job | yes | Permanently delete a job. Active jobs are refused. |