Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.RohitYajee8076/backburner run npm test in background"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Put your AI agent's slow work on the back burner. Keep cooking.
Background tasks for AI agents that outlive the conversation — start a long job, close the client, and the result is still waiting when you come back.
Durable & Restart-Proof ◦ Zero Infrastructure ◦ MCP Tasks (2026-07-28) ◦ Windows & Unix
📦 PyPI • 🗂️ MCP Registry • 🐛 Issues • 📄 MIT
v1.0 — implements the official MCP Tasks extension
(SEP-2663,
io.modelcontextprotocol/tasks). A Tasks-capable client can turn a
start_task call into a durable task and drive it with tasks/get,
tasks/update, and tasks/cancel — the standard async-job protocol — while
the five plain tools keep working for every other client. Built against the
2026-07-28 spec (mcp 2.0).
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, ChatGPT,
Gemini, GitHub Copilot, Cursor, 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.
Related MCP server: Background Process MCP
Because that lives inside the conversation — it disappears the moment the session ends. Close the chat, restart the client, reboot the laptop, and any in-session background work (and its output) is gone.
backburner keeps every task and its full output on disk (SQLite +
per-task log files under ~/.backburner/), so your work outlives the session
that started it:
Start now, collect later — even in a different chat. A task you launch today is still listed, with its result, in a brand-new session tomorrow.
Restart-proof. State survives the server, the client, and the machine
restarting. Finished tasks keep their output; a task cut off by a crash is
honestly marked interrupted, never silently dropped.
No waiting, no blocking. A 10-minute tool call no longer freezes the conversation or times out and loses the work.
See it for yourself — a real two-process proof (no mock-ups):
python docs/demo_restart.pyIt starts a job in one process, exits, then a separate process — which never saw the task id — finds the finished work waiting on disk.
Built on the MCP Tasks pattern, formalized in the 2026-07-28 spec release
(SEP-2663):
backburner speaks it natively (tasks/get / tasks/update / tasks/cancel)
and exposes the same engine as plain tools, so it works with every client
today.
Tool | What it does |
| Run a shell command in the background, returns a task id immediately |
|
|
| Captured output — works mid-run too, so you can peek at progress |
| Kill the task and its whole process tree |
| Recent tasks, newest first |
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 runZero 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.
backburner is a standard stdio MCP server — it works with any MCP-compatible
client, including:
Claude Code · Claude Desktop · OpenAI (ChatGPT desktop / Agents SDK) · Google Gemini (Gemini CLI) · GitHub Copilot (VS Code) · Cursor · Windsurf · Cline · Zed — and any other client that speaks MCP.
First install the package:
pip install backburner-mcpclaude mcp add backburner -- python -m backburner.serverMost clients use the same standard config block — add backburner to your
client's MCP config (see your client's docs for where that file lives):
{
"mcpServers": {
"backburner": {
"command": "python",
"args": ["-m", "backburner.server"]
}
}
}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.
Task timeouts and max-runtime limits
Allowlist/denylist for commands
PyPI release — pip install backburner-mcp
Listed on the official MCP Registry
MCP Tasks extension (spec 2026-07-28, SEP-2663) — native tasks/get /
tasks/update / tasks/cancel alongside the plain tools
Task push updates (notifications/tasks) — live status without polling
Local web dashboard — watch tasks live in the browser
Structured progress reporting (parse % / step markers from output)
MIT
Cancel a running task, killing its whole process tree.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals the side effect of 'killing its whole process tree,' which is critical for an agent to understand the destructive scope. It does not detail return values or error cases, but for a single-purpose cancel tool, this is substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, front-loaded with the core action ('Cancel a running task') and followed by the key side effect. Every word earns its place; it is an excellent example of concise specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides the essential behavioral context and side effect. It could mention what happens if the task is not running, but for a straightforward cancel operation, the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (task_id) with 0% description coverage, and the tool description does not mention the parameter at all. While the name 'task_id' is self-explanatory, the description adds no meaning beyond the schema, failing to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Cancel') on a specific resource ('a running task'), and adds the detail of 'killing its whole process tree,' which distinguishes it from sibling tools like task_status or start_task. It is unambiguous and directly conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for running tasks only, but does not explicitly contrast with alternatives or state when to avoid using it. There is no mention of when to use this versus task_status or task_result, leaving the decision to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent tasks, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses only the ordering (newest first) but omits important behavioral details such as whether completed tasks are included, the meaning of 'recent' (time window), pagination, or any read-only scoping. With no annotations provided, the description carries full responsibility and only partially covers it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It conveys core purpose and ordering efficiently, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one optional parameter and an output schema, the description is lacking contextual completeness. It does not clarify the scope of 'recent tasks' (e.g., user-specific, status, time range), which is critical for correct invocation. The output schema mitigates return-value ambiguity, but the missing behavioral context remains a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'limit' has a default of 20 in the schema, but the description does not explain its effect (e.g., maximum number of tasks returned). Since schema coverage is 0%, the description was expected to compensate but adds no meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List recent tasks, newest first' clearly identifies the action (list) and resource (tasks) with a specific ordering. It distinguishes itself from sibling tools that manage individual tasks (start_task, task_status, task_result, cancel_task) rather than providing a list overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to retrieve an overview of recent tasks, but it does not explicitly state when to use it versus alternatives. No exclusions or prerequisites are mentioned, so the usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a shell command as a background task and return immediately.
Args: command: The shell command to run (e.g. "pytest -q" or "npm run build"). cwd: Working directory for the command. Defaults to the server's cwd. timeout_seconds: If set, the task is killed and marked 'timed_out' when it runs longer than this. Recommended for unattended jobs.
Returns the new task's id and initial status. The command keeps running after this call returns — use task_status / task_result to follow it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| command | Yes | ||
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: the command runs in the background, the call returns immediately, the task can be killed if it exceeds timeout_seconds, and a new task id and initial status are returned. This is sufficient transparency for the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary, a clear Args block, and a follow-up note. Every sentence adds value, and the format makes it easy to scan and understand without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three parameters and no output schema, yet the description covers what is returned (task id and initial status), how the task continues to run, and how to follow up using sibling tools. This provides complete context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides detailed semantics for all three parameters: command is exemplified, cwd defaults to the server's cwd, and timeout_seconds causes the task to be killed and marked 'timed_out'. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Start a shell command as a background task and return immediately.' It specifies both the verb and resource, and distinguishes itself from siblings by explaining follow-up with task_status/task_result, making it clear this tool initiates the task while others monitor or cancel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool (to start a background command) and what to do after (use task_status / task_result to follow it). It also provides a specific guideline for timeout_seconds, recommending it for unattended jobs, which helps the agent decide when to set this parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a task's captured output (stdout+stderr merged).
Args: task_id: The task to inspect. Works for finished AND still-running tasks, so you can peek at live progress. tail_lines: How many trailing lines of output to return.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| tail_lines | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that stdout and stderr are merged, that it supports both finished and running tasks (enabling live progress peeking), and that tail_lines limits the output. This is useful behavioral context beyond a simple 'get output' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary followed by a clear Args section. Every sentence adds value, with no redundant or filler text. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the essential behaviors: what output is returned, how the output is merged, and the ability to inspect running tasks. It does not specify the exact return format, but the description is sufficiently complete for a straightforward output-fetching tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so by explaining both parameters: task_id is 'the task to inspect' and can be used on running tasks, and tail_lines specifies 'how many trailing lines of output to return.' This adds meaningful semantics beyond the bare schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a task's captured output (stdout+stderr merged).' The verb 'Get' plus the resource 'task's captured output' is specific, and the scope (stdout+stderr) distinguishes it from sibling tools like task_status or cancel_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by noting it works for 'finished AND still-running tasks, so you can peek at live progress.' This implies when to use it (to inspect output, especially for in-progress tasks), though it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check on a task: working, completed, failed, cancelled, timed_out, or interrupted.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It lists possible statuses but does not disclose whether the operation is read-only, error behavior, auth requirements, or what the response structure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, every word earns its place; no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The enumeration of statuses provides useful behavioral context, but missing usage guidance, return format, and error handling leaves gaps. For a single-parameter tool with no output schema and no annotations, this is minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter task_id is not mentioned in the description beyond the implicit 'task'. Schema description coverage is 0%, and the description does not clarify the format, requiredness, or source of task_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'check' with 'task' as the resource and enumerates six possible statuses, making its purpose clear. It differentiates from siblings like start_task and cancel_task, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus task_result or list_tasks. The status list implies usage but there are no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0cancel_tasklist_tasksstart_tasktask_resulttask_statusScored across 5 tools
Each tool targets a distinct lifecycle stage: start_task initiates, task_status reports state, task_result retrieves output, cancel_task terminates, and list_tasks enumerates. No two tools overlap in purpose.
All tool names follow a consistent verb_noun pattern in snake_case: start_task, task_status, task_result, cancel_task, list_tasks. There are no deviations or mixed conventions.
Five tools is a perfect scope for a background task manager: create, monitor, retrieve output, cancel, and list. Each tool has a clear role, and no redundant or missing entries.
The tool set covers the full lifecycle of a background task: start, poll status, fetch output, cancel, and list. The timeout behavior in start_task also handles timed-out tasks. No obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Persistent work tracking for AI agents: tasks, status and history that follow you across machines
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
