TaskChampion MCP

TaskChampion MCP

Taskwarrior 3.x、TaskChampion、Timewarrior 用の Model Context Protocol サーバーです。

ターミナルから生活を管理する、ひげをたくわえた Unix 愛好家やキーボードの達人へ。LLM にも手伝ってもらいませんか。 🧔⌨️

最新リリース： v1.0.4 — pip install taskchampion-mcp / uvx taskchampion-mcp

---

これは何ですか？

TaskChampion MCP は、LLM が Taskwarrior のタスクや Timewarrior の時間記録を読み取り、作成、変更、管理できる Model Context Protocol サーバーです。task および timew の CLI ツールをラップし、互換性のある任意の AI アシスタントが呼び出せる構造化された MCP ツールとして公開します。

なぜ作ったのですか？ 作者は自宅のサーバーで TaskChampion をセルフホストしており、タスクデータベースの管理権を手放さずに、LLM とプロジェクト計画、タスクの分解、時間追跡で連携できるすっきりとした方法を求めていました。

---

対応プラットフォーム

プラットフォーム	トランスポート	ステータス
Neovim（Claude Code CLI 経由）	stdio	v1.0.4
Cursor	stdio	v1.0.4
Windsurf	stdio	v1.0.4
VS Code（Copilot MCP）	stdio	v1.0.4
Claude Desktop	stdio	v1.0.4
HTTP/SSE トランスポート	HTTP/SSE	v1.x 以降に延期

要件：

• Python 3.10+
• Taskwarrior 3.x（TaskChampion 同期）
• Timewarrior（任意。時間追跡機能用）

---

クイックインストール

# With uv (recommended)
uv tool install taskchampion-mcp

# With pip
pip install taskchampion-mcp

次に、IDE の MCP 設定で以下を使用するように設定します：

{
  "mcpServers": {
    "taskchampion": {
      "command": "taskchampion-mcp-server",
      "args": []
    }
  }
}

ターゲット別のインストールガイド：Claude Desktop | Windsurf | Cursor | Neovim

---

初回起動

config.toml がない状態で新規インストールすると、サーバーはオンボーディングモードで起動します。すべてのツールが tools/list に表示されますが、オンボーディングが完了するまでは、操作ツールは構造化された schema_unset エラーを返します（ADR 19）。オンボーディングを完了するには、~/.config/taskchampion-mcp/config.toml に次の 2 つのキーを保存します：

• role — LLM に許可する操作（CONTRIBUTOR / GENERATOR / MANAGER）
• schema または schema_path — サーバーが検証に使用するタスクスキーマ

設定方法は 3 通りあります：

1. LLM に案内してもらう。 設定ファイルなしで IDE を MCP サーバーに接続し、次のように尋ねます：「TaskChampion MCP のセットアップを手伝ってください。」 LLM はまず get_runtime_capabilities を呼び出し、mode: "onboarding" を確認してから、get_initialization_status -> propose_initialization_options -> use_preset_schema（または save_initial_schema）を使用します。成功するとサーバーが自動で再読み込みされるため、再起動は不要です。
2. CLI ウィザードを実行する： ./dev.sh init（対話形式）、または ./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive（スクリプト実行向け）。
3. config.toml を手動で編集する — quick_start.md を参照してください。2 つのキーを設定したら、LLM から reload_configuration を呼び出します（または IDE を再起動します）。

3 つの方法は相互に置き換え可能で、同じ状態になります。誰が入力を担当するかに応じて選んでください。選び方については初期化フローのガイドを参照してください。

---

権限レベル

3つの累積的なロールを通じて、LLM がタスクに対して実行できる操作を制御します。

ロール	読み取り	注釈／変更	作成	完了／削除
CONTRIBUTOR	✅	✅	❌	❌
GENERATOR	✅	✅	✅	❌
MANAGER	✅	✅	✅	✅

ロールは ~/.config/taskchampion-mcp/config.toml で設定します。

[server]
role = "GENERATOR"  # CONTRIBUTOR | GENERATOR | MANAGER

---

タスクスキーマ

Taskwarrior は、UDA（ユーザー定義属性）を通じてカスタムワークフローに対応しています。TaskChampion MCP には、LLM にタスク構造を学習させるスキーマプリセットが用意されています。

スキーマ	説明
minimal	組み込みフィールドのみ（優先度、プロジェクト、タグ）
gtd	Getting Things Done（コンテキスト、エネルギー、次のアクション）
scrum	スプリントベース（ストーリーポイント、スプリント ID、受け入れ条件）
kanban	ボードの列、WIP 制限、サービスクラス
authors_custom_example	ライフサイクルのフェーズ、仮説主導型の調査、LLM の出所追跡を含む、高度な実例

初回実行時に、MCP はスキーマの選択、または既存のタスクからの自動生成を促します。

---

セキュリティ

このツールを使うと、LLM はタスク管理 CLI に間接的にアクセスできます。セキュリティは必須です。

• シェルを実行しない — CLI の呼び出しにはすべて subprocess の引数リストを使用し、shell=True は決して使用しません
• 入力のサニタイズ — すべての LLM 入力は、CLI に渡す前に許可リストに照らして検証されます
• レート制限 — 1 分あたり／1 時間あたりの上限を設定でき、制御不能なループを防ぎます
• 監査ログ — すべての操作について、タイムスタンプ、ツール、パラメーター、結果、result_code を記録します
• コードタグ付きエンベロープ — すべてのツール応答に、機械的な分岐処理に安全に使える安定した code フィールドが含まれます
• ドライランモード — 破壊的な操作はすべて、変更を加えずにプレビューする dry_run に対応しています
• 確認モード — 確認が有効な場合、ライフサイクル操作には明示的な確認トークンが使用されます
• 機密フィールドのマスキング — 設定したフィールドは LLM の応答に表示されません

セキュリティと可観測性の設計の全容については、ADR 9、ADR 13、ADR 14 を参照してください。

---

Taskwarrior との互換性

バージョン	状態
Taskwarrior 3.x（TaskChampion）	✅ 完全にサポート
Taskwarrior 2.x（Taskserver/taskd）	⏳ 今後のリリースで対応予定

最新の Taskwarrior 3.x + TaskChampion スタックに注力しています。Taskserver（taskd）は非推奨であり、今後のバージョンではサポートが限定されます。ADR 8 を参照してください。

---

ドキュメント

フォルダー／ファイル	内容
docs/adrs/	アーキテクチャ決定記録
docs/references/	上流ツールのリファレンス（Taskd、TaskChampion、Timewarrior）
docs/manuals/quick_start.md	config.toml の手動設定
docs/manuals/configuration_reference.md	優先順位のルールを含む、設定キーの完全なリファレンス
docs/manuals/schema_authoring.md	カスタムタスクスキーマの作成
docs/manuals/security_model.md	エンドユーザー向けのセキュリティ制御
docs/manuals/initialization_flows.md	使用する初期化方法（LLM 主導、CLI、手動編集）
docs/manuals/targets/	IDE ごとのインストールガイド（Claude Desktop、Windsurf、Cursor、Neovim）
docs/manuals/logrotate.md	監査ログのローテーション
docs/llm_context/	LLM エージェントのガイドラインと追跡対象の前提
docs/CONTRIBUTING.md	貢献方法（ブランチ、PR、バージョン管理）
docs/ROADMAP.md	機能ロードマップ（v0.1.0 → v1.0.0）
docs/releases/v1.0.4.md	v1.0.2 のリリースノートとインストールリンク
docs/manuals/release_checklist.md	タグ付け前の公開チェックリスト
src/taskchampion_mcp/schemas/	同梱のタスクスキーマプリセット（TOML）
scripts/setup_remote.sh	リモートホストを一括でセットアップするスクリプト

---

トラブルシューティング

初回実行時や設定に関する一般的な問題について説明します。詳細な手順は docs/manuals/quick_start.md と docs/manuals/initialization_flows.md を参照してください。

症状	考えられる原因	解決方法
接続後、ツールが schema_unset エラーを返す	~/.config/taskchampion-mcp/config.toml に role または schema／schema_path のいずれかがない	[server] の下に両方を追加し、reload_configuration を呼び出します（または再起動します）。
Linux で Claude Desktop のインストールが完了しても、taskchampion が表示されない	dev.sh の v0.3.0 より前の小文字パスのバグ	v0.3.0 以降に更新します。Linux では ~/.config/Claude/ の C は大文字です。
set_role("MANAGER") が role_elevation_forbidden を返す	MCP 経由での自己昇格は禁止されています（ADR 17）	config.toml を手動で編集し、reload_configuration を呼び出します。
MCP サーバーの起動時に Taskwarrior not found on PATH で失敗する	task がインストールされていないか、MCP サーバーの PATH に存在しない	Taskwarrior 3.x をインストールします。必要に応じて、設定で task_binary を指定します。
Cowork／Claude Desktop：終了時にインストール用 JSON が上書きされる	Claude Desktop の実行中に設定を書き込んだ	先に Claude Desktop を終了するか、./dev.sh reinstall claude -r を使用します。
ツール一覧にオンボーディングツールもコントリビューターツールも含まれていない	サーバーの起動に失敗した（stderr を確認してください）	シェルから taskchampion-mcp-server を実行して、エラーを確認します。

より詳しい障害モードについては、すべての MCP ツールが安定した error_code フィールドを返し（ADR 14）、すべての呼び出しがデフォルトで ~/.local/share/taskchampion-mcp/audit.log に監査ログとして記録されます（ADR 13）。

---

貢献

完全なガイドは docs/CONTRIBUTING.md を参照してください。主なポイントは次のとおりです。

• dev からブランチを作成し、qa に PR を送り、qa から main にリリースします
• セマンティックバージョニング（vMAJOR.MINOR.PATCH）
• LLM の支援を受けた貢献には、支援を受けたことを明記する必要があります（docs/llm_context/AGENTS.md を参照）
• 検証されていない前提はすべて docs/llm_context/assumptions_and_ideas.md に記録する必要があります

---

ライセンス

Apache License 2.0 — 個人利用および商用利用に自由にお使いいただけます。NOTICE ファイルによる帰属表示が必要です。

Copyright 2026 gabiup2

---

このプロジェクトは、Windsurf Cascade 経由で Claude claude-sonnet-4-20250514 の支援を受けて作成されました。