Content
<!-- 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](https://pypi.org/project/backburner-mcp/) • 🗂️ [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=backburner) • 🐛 [Issues](https://github.com/RohitYajee8076/backburner/issues) • 📄 [MIT](LICENSE)
</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):
```bash
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
```bash
pip install backburner-mcp
```
### Claude Code
```bash
claude mcp add backburner -- python -m backburner.server
```
### Claude Desktop / other clients
```json
{
"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
