io.github.RohitYajee8076/backburner

<!-- mcp-name: io.github.RohitYajee8076/backburner -->

<div align="center">

<img src="docs/banner.png" alt="backburner — background tasks for AI agents" />

<br/> <br/>

Put your AI agent's slow work on the back burner. Keep cooking.

<b>Background Tasks  ◦  Zero Infrastructure  ◦  Survives Restarts  ◦  Windows & Unix</b>

<br/>

📦 PyPI  •  🗂️ MCP Registry  •  🐛 Issues  •  📄 MIT

</div>

---

📢 Updates

• v0.2.1 — output with non-ASCII characters (✓, emoji, any non-English text) no longer crashes tasks on Windows.
• v0.2.0 — exit_code is no longer reported for cancelled/timed-out tasks (it was an artifact of the kill, not a real result); new animated demo below.
• v0.1.x — first release: 5 tools, task timeouts, command allow/deny policy. Listed on the official MCP Registry as io.github.RohitYajee8076/backburner.

---

backburner is an MCP server that gives any AI assistant (Claude, and any other MCP client) the ability to run long shell commands as background tasks — start a test suite, a build, a scrape, a batch job — then keep working and check back for the results, instead of sitting frozen until it finishes.

🔥 Why

AI agents are bad at waiting. A tool call that takes 10 minutes blocks the whole conversation — or times out and loses the work entirely. The MCP specification is formalizing a Tasks pattern for exactly this problem (extension finalized in the 2026-07-28 spec release); backburner brings that workflow to every client today via plain tools, with first-class Tasks-extension support on the roadmap.

🧰 Tools

Tool	What it does
start_task(command, cwd?, timeout_seconds?)	Run a shell command in the background, returns a task id immediately
task_status(task_id)	working / completed / failed / cancelled / timed_out / interrupted
task_result(task_id, tail_lines?)	Captured output — works mid-run too, so you can peek at progress
cancel_task(task_id)	Kill the task and its whole process tree
list_tasks(limit?)	Recent tasks, newest first

✨ Features

• Survives restarts — tasks are tracked in SQLite under ~/.backburner/; output is captured to per-task log files. If the server dies mid-task, orphaned tasks are honestly marked interrupted, never silently lost.

• Real cancellation — kills the full process tree (worker processes included), on Windows and Unix.

• Peek at live progress — task_result on a running task returns the output so far.

• Timeouts — pass timeout_seconds and a runaway task is killed and honestly marked timed_out instead of hanging forever.

• Command policy — restrict what the AI may run with environment variables (regexes, comma-separated; deny always wins):

  BACKBURNER_ALLOW="^pytest,^npm (test|run build)"   # only these may run
  BACKBURNER_DENY="rm -rf,shutdown,format"           # these never run
  

• Zero infrastructure — stdlib only (SQLite, subprocess, threads). No Redis, no Celery, no Docker.

• Tested — a pytest suite covers the full job lifecycle: completion, failure, cancellation, timeouts, crash recovery, and the command policy.

🚀 Install

pip install backburner-mcp

Claude Code

claude mcp add backburner -- python -m backburner.server

Claude Desktop / other clients

{
  "mcpServers": {
    "backburner": {
      "command": "python",
      "args": ["-m", "backburner.server"]
    }
  }
}

🔒 Security note

backburner executes the shell commands the AI sends it, with your user's permissions. That is its job — but treat it like giving your agent a terminal. Run it only with clients whose tool-use you review/approve, prefer permission modes that require confirmation for start_task, and use BACKBURNER_ALLOW / BACKBURNER_DENY to scope what may run.

🗺️ Roadmap

• [x] Task timeouts and max-runtime limits
• [x] Allowlist/denylist for commands
• [x] PyPI release — pip install backburner-mcp
• [x] Listed on the official MCP Registry
• [ ] MCP Tasks extension support (spec 2026-07-28) — native tasks/get, tasks/cancel alongside the plain tools
• [ ] Local web dashboard — watch tasks live in the browser
• [ ] Structured progress reporting (parse % / step markers from output)

📄 License

MIT