queue-mcp

A task queue for Claude Code. Line up work from another terminal, and Claude drains it one item at a time.

The problem

Type at the Claude Code prompt while a turn is running and your message gets steered into that turn at the next tool boundary. It does not wait. That is the right behaviour for "no, use the other file" mid-edit, but it makes it impossible to line up three follow-ups and walk away.

This queue lives outside the conversation, so nothing you add can disturb the running turn. Wanted upstream too: #50246 (217 reactions), #73661, #82348, #63190.

Install

Via mcp-orchestrator, which also keeps it running:

mcp_install("queue")

Or by hand:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\run.ps1
claude mcp add --transport http --scope user queue http://127.0.0.1:8766/mcp

Tell Claude to use it

This step is what makes it automatic. Installing the server only provides the queue; Claude will not use it for anything until told to. Add this to your CLAUDE.md, then talk to Claude exactly as usual and every task you give it goes through the queue.

## Task queue (queue-mcp)

The `queue` MCP server holds a per-session work queue. Drain it in order.

**Your session id** is the UUID in your scratchpad path. Pass it as
`session_id` to every queue tool. Never guess it, and never reuse one from an
earlier conversation.

**Everything the user asks you to do goes in the queue first, single tasks
included.** Do not weigh up whether a request is big enough to be worth
queueing. That judgment is exactly what fails: under momentum it always comes
out "this one is small, just start", and the rule quietly stops existing.

The test is **do vs say**, and it is the only judgment you make:
- If fulfilling the request means *doing* something, writing, editing, running,
  building, investigating, it goes in the queue before any of it starts.
- If it means only *saying* something, a question about this conversation, an
  opinion, a design you are discussing, answer inline and queue nothing.

On receiving a request that passes the test:

1. `queue_add` each step as its own item, in order, before doing any work. A
   chain ("do X, then Y") is one item per step.
2. Check `queue_current`. If nothing is in progress, `queue_next` immediately
   and start the first item.
3. If something is already in progress, just append and say so. Never jump the
   queue or run two items at once.

**The loop:**
1. `queue_next` claims one item and marks it in progress.
2. Do the work.
3. `queue_complete` with a one-line result. Mark `failed: true` if it did not
   work; do not silently mark it done.
4. Back to step 1. Stop when `queue_next` returns `drained: true`.

**Rules that matter:**
- **One at a time.** Never claim a new item while one is in progress.
- **`drained: true` means stop**, not "go look for more work".
- **A failed item does not block the queue.** Record it, report it, move on,
  and flag it in the final summary.
- **The queue records the user's intent, not yours.** Never queue work they did
  not ask for, beyond splitting their request into steps.
- **If the queue server is unreachable, say so and do the work anyway.** The
  queue is a coordination aid, not a gate.

Trim it to taste, but keep the do vs say test and the one-at-a-time rule. Those two carry most of the behaviour.

Adding work while it runs

.\q.ps1 add "fix the failing auth test"
.\q.ps1 add --next "urgent: revert the migration"
.\q.ps1 list

Claude claims one item, works it, marks it done, then claims the next. It stops when the queue reports drained.

Tools

Tool	Purpose
queue_add	Append or insert an item
queue_list / queue_current	What is queued, what is running
queue_next	Claim the next item
queue_complete	Mark done or failed
queue_remove / queue_move / queue_clear	Edit the queue
queue_sessions / queue_history	Every known queue, and past work

Worth knowing

• Queues are per session. Every tool takes session_id, because an MCP server cannot tell which session is calling it.
• Data lives in ~/.queue-mcp. Restarting the server loses nothing.
• The CLI writes the same files as the server, so adding work does not depend on the server being up.
• The loop is model-mediated, not enforced. Claude queues and drains because CLAUDE.md tells it to, not because anything makes it. A Stop hook would make it strict.

Config: QUEUE_MCP_PORT, QUEUE_MCP_HOST, QUEUE_MCP_HOME.