backburner

---

📢 更新情報

• v1.0 — MCP の公式 Tasks 拡張機能を実装しました (SEP-2663, io.modelcontextprotocol/tasks)。Tasks に対応したクライアントは、 start_task の呼び出しを永続的なタスクに変換し、 tasks/get、tasks/update、tasks/cancel を使って標準の非同期ジョブプロトコルで処理できます。 一方、5 つの通常のツールは他のすべてのクライアントでも引き続き動作します。 2026-07-28 の仕様（mcp 2.0）に基づいて構築されています。
• v0.2.1 — 非 ASCII 文字（✓、絵文字、英語以外のテキスト）を含む出力によって、Windows でタスクがクラッシュすることはなくなりました。
• v0.2.0 — キャンセルまたはタイムアウトしたタスクでは exit_code が報告されなくなりました（これは実際の結果ではなく、強制終了によるものでした）。以下に新しいアニメーションデモを追加しました。
• v0.1.x — 初回リリース：5 つのツール、タスクのタイムアウト、コマンドの許可・拒否ポリシー。 公式 MCP Registry に io.github.RohitYajee8076/backburner として登録されています。

---

backburner は、Claude、ChatGPT、Gemini、GitHub Copilot、Cursor、その他あらゆる MCP クライアントなどの AI アシスタントに、長時間かかるシェルコマンドをバックグラウンドタスクとして実行する機能を提供する MCP サーバーです。テストスイート、ビルド、スクレイピング、バッチジョブなどを開始したら、完了まで待って会話が止まるのではなく、作業を続けて後から結果を確認できます。

🔥 クライアントに組み込まれたバックグラウンドモードを使わないのはなぜですか？

その機能は会話の中だけで動くからです。セッションが終了した瞬間に消えてしまいます。チャットを閉じたり、クライアントを再起動したり、ノート PC を再起動したりすると、セッション内で実行中のバックグラウンド作業とその出力はすべて失われます。

backburner はすべてのタスクとその完全な出力をディスク上（SQLite と ~/.backburner/ 以下のタスクごとのログファイル）に保持するため、作業を開始したセッションが終了した後も残ります。

• 今すぐ開始して、後で取得できます。別のチャットでも確認できます。 今日開始したタスクは、明日新しいセッションを開いても、結果とともに一覧に残っています。
• 再起動にも対応。 状態はサーバー、クライアント、マシンの再起動後も保持されます。完了したタスクの出力は残り、クラッシュで中断されたタスクには interrupted と正直に表示され、黙って破棄されることはありません。
• 待ち時間もブロックもありません。 10 分かかるツール呼び出しによって会話が止まったり、タイムアウトして作業結果が失われたりすることはありません。

実際にご確認ください。モックではなく、2 つのプロセスを使った実証です。

python docs/demo_restart.py

1 つ目のプロセスでジョブを開始して終了します。その後、タスク ID を知らない別のプロセスが、完了した作業をディスク上から見つけます。

2026-07-28 の仕様リリースで正式化された MCP Tasks パターンに基づいています (SEP-2663)。 backburner はこのパターンをネイティブにサポートし（tasks/get / tasks/update / tasks/cancel）、同じエンジンを通常のツールとしても公開するため、現在すべてのクライアントで動作します。

🧰 ツール

ツール	内容
start_task(command, cwd?, timeout_seconds?)	シェルコマンドをバックグラウンドで実行し、すぐにタスク ID を返します
task_status(task_id)	working / completed / failed / cancelled / timed_out / interrupted
task_result(task_id, tail_lines?)	キャプチャされた出力です。実行中にも使えるため、進捗を確認できます
cancel_task(task_id)	タスクと、そのプロセスツリー全体を終了します
list_tasks(limit?)	最近のタスクを新しい順に表示します

✨ 機能

• 再起動後も維持 — タスクは ~/.backburner/ 内の SQLite で追跡され、 出力はタスクごとのログファイルに保存されます。タスクの実行中にサーバーが停止した場合、 孤立したタスクには interrupted と正しく記録され、ひそかに失われることはありません。

• 確実なキャンセル — Windows と Unix の両方で、ワーカープロセスを含む プロセスツリー全体を終了します。

• 実行中の進捗を確認 — 実行中のタスクに対する task_result は、 それまでの出力を返します。

• タイムアウト — timeout_seconds を指定すると、暴走したタスクは終了され、 永遠にハングする代わりに timed_out と正しく記録されます。

• コマンドポリシー — 環境変数で AI が実行できるコマンドを制限できます （正規表現をカンマ区切りで指定。拒否ルールが常に優先されます）。

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

• インフラ不要 — 標準ライブラリのみを使用します（SQLite、subprocess、threads）。 Redis、Celery、Docker は不要です。

• テスト済み — pytest スイートで、完了、失敗、キャンセル、タイムアウト、 クラッシュからの復旧、コマンドポリシーを含むジョブのライフサイクル全体をカバーしています。

🚀 インストール

backburner は標準的な stdio MCP サーバーで、以下を含むあらゆる MCP 対応 クライアントで動作します。

Claude Code · Claude Desktop · OpenAI（ChatGPT desktop / Agents SDK）· Google Gemini（Gemini CLI）· GitHub Copilot（VS Code）· Cursor · Windsurf · Cline · Zed、および MCP に対応するその他すべてのクライアント。

まずパッケージをインストールします。

pip install backburner-mcp

Claude Code

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

その他（Claude Desktop、Cursor、VS Code / Copilot、Windsurf、Gemini CLI など）

ほとんどのクライアントでは、同じ標準設定ブロックを使います。クライアントの MCP 設定に backburner を追加してください（設定ファイルの場所は、クライアントのドキュメントを参照してください）。

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

🔒 セキュリティに関する注意

backburner は、AI から送られたシェルコマンドをユーザーの権限で実行します。 それがこのツールの役割ですが、エージェントにターミナルを渡すのと同じように扱ってください。 ツールの使用を確認・承認できるクライアントでのみ実行し、start_task に確認を求める 権限モードを優先して使用し、実行を許可する範囲を BACKBURNER_ALLOW / BACKBURNER_DENY で設定してください。

🗺️ ロードマップ

• タスクのタイムアウトと最大実行時間の制限
• コマンドの許可リスト／拒否リスト
• PyPI リリース — pip install backburner-mcp
• 公式 MCP Registry に掲載
• MCP Tasks 拡張機能（spec 2026-07-28、SEP-2663）— 通常のツールに加え、 ネイティブな tasks/get / tasks/update / tasks/cancel
• タスクのプッシュ更新（notifications/tasks）— ポーリングなしでライブステータスを確認
• ローカル Web ダッシュボード — ブラウザーでタスクをリアルタイムに監視
• 構造化された進捗レポート（出力から % / ステップマーカーを解析）

📄 ライセンス

MIT