MCP Tasks

MCP Tasks 📋

効率的なタスクマネージャーです。複数のファイル形式（Markdown、JSON、YAML）に対応した強力な検索、フィルタリング、整理機能を備えながら、ツールの混乱を最小限に抑え、LLM の予算を効率的に活用できるよう設計されています。

📚 目次

• ✨ 機能
• 🚀 クイックスタート
• 🤖 AI 連携のヒント
• 🔧 インストール例
• 📁 対応ファイル形式
• 🛠️ 利用可能なツール
• 🎛️ 環境変数
• 📊 ファイル形式
• 🖥️ サーバーの使用方法
• 💻 CLI の使用方法
• 🧪 開発
• 🛠️ トラブルシューティング
• AI にタスクファイルを直接編集させない理由
• 🤝 コントリビューション
• 📄 ライセンス
• 🔗 リンク

✨ 機能

• ⚡ 超効率的な設計：AI の混乱を抑える最小限のツール数（5 個）
• 🎯 予算を最適化：一括操作、スマートなデフォルト設定、自動操作により、LLM API の呼び出しを最小限に抑えます
• 🚀 複数の形式に対応：Markdown（.md）、JSON（.json）、YAML（.yml）のタスクファイル
• 🔍 強力な検索：大文字と小文字を区別しないテキスト／ステータスのフィルタリング（OR ロジック対応）と、ID による検索
• 📊 スマートな整理：カスタマイズ可能なワークフローの状態を使った、ステータスベースのフィルタリング
• 🎯 位置ベースのインデックス作成：0 始まりの挿入による簡単なタスクの並べ替え
• 📁 複数のソースに対応：複数のタスクファイルを同時に管理
• 🔄 リアルタイム更新：選択した形式に変更が自動的に保存されます
• 🤖 WIP の自動管理：進行中のタスク数の上限を自動的に管理
• 🚫 重複防止：タスクの重複を自動的に防止
• 🛡️ 型安全：Zod による検証を備えた、完全な TypeScript サポート
• 🔒 超安全：AI がタスクを書き換えたり削除したりすることはできません（有効にした場合を除く）。追加と移動のみ可能です
• 📅 リマインダーは任意：AI が常に確認し、管理できる専用のリマインダーセクションを有効にできます

🚀 クイックスタート

Cursor の場合は ~/.cursor/mcp.json に、Claude Desktop の場合は ~/.config/claude_desktop_config.json に追加します。

オプション 1：NPX（推奨）

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}

オプション 2：Docker

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-tasks"
      ]
    }
  }
}

🤖 AI 連携のヒント

AI にこれらのツールを使わせるには、任意のパスと .md（推奨）、.json、.yml を指定して、次のようなプロンプトから始められます。

Use mcp-tasks tools to track our work in path/to/tasks.md

新しいタスクや更新したタスクについて伝える場合は、プロンプトの末尾に次の内容を追加できます。

use mcp-tasks

AI の作業中にタスクを追加する場合： AI の操作を妨げずに安全にタスクを追加するには、別のターミナルからCLI を使用してください。

npx mcp-tasks add "Your new task text" "To Do" 0

🔧 インストール例

カスタム環境を含む完全な設定：

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"],
      "env": {
        "STATUS_WIP": "In Progress",
        "STATUS_TODO": "To Do",
        "STATUS_DONE": "Done",
        "STATUS_REMINDERS": "Reminders",
        "STATUS_NOTES": "Notes",
        "STATUSES": "In Progress,To Do,Done,Backlog,Reminders,Notes",
        "AUTO_WIP": "true",
        "PREFIX_TOOLS": "true",
        "KEEP_DELETED": "true",
        "TRANSPORT": "stdio",
        "PORT": "4680",
        "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
      }
    }
  }
}

リモートアクセス用の HTTP トランスポート：

まずサーバーを起動します。

TRANSPORT=http PORT=4680 npx mcp-tasks

次に：

{
  "mcpServers": {
    "mcp-tasks": {
      "type": "streamableHttp",
      "url": "http://localhost:4680/mcp"
    }
  }
}

📁 対応しているファイル形式

拡張子	形式	最適な用途	自動作成
.md	Markdown	人が読みやすいタスクリスト	✅
.json	JSON	構造化データ、API	✅
.yml	YAML	設定ファイル	✅

ファイル形式は拡張子から自動検出されます。 すべての形式で同じ機能を利用でき、同じプロジェクト内で混在させることもできます。

推奨：人が読みやすく編集しやすい Markdown（.md）

⚠️ 警告：タスク以外のコンテンツが失われないよう、既存のタスクファイルではなく新しいファイルから始めてください。

🛠️ 利用可能なツール

PREFIX_TOOLS=true（デフォルト）の場合、すべてのツール名に tasks_ が付きます。

ツール	説明	パラメーター
tasks_setup	タスクファイルを初期化します（ファイルがない場合は作成し、.md、.json、.yml に対応）	source_path、workspace?
tasks_search	条件を指定してタスクを検索します	source_id、statuses?、terms?、ids?
tasks_add	指定したステータスにタスクを追加します	source_id、texts[]、status、index?
tasks_update	IDでタスクを更新します	source_id、ids[]、status、index?
tasks_summary	タスク数と進行中の作業を取得します	source_id

IDの形式：source_id（ファイルパスから取得）とタスクの id（タスクのテキストから取得）は、どちらも4文字の英数字です（例："xK8p"、"m3Qw"）。

ツールの使用例

タスクファイルをセットアップ：

tasks_setup({
  workspace: "/path/to/project",
  source_path: "tasks.md"  // relative to workspace or absolute
  // source_path: "tasks.json"
  // source_path: "tasks.yml"
})
// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// Source ID (4-char alphanumeric) is used for all subsequent operations

タスクを追加：

tasks_add({
  source_id: "xK8p", // From setup response
  texts: ["Implement authentication", "Write tests"],
  status: "To Do",
  index: 0  // Add at top (optional)
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}

検索とフィルタリング：

tasks_search({
  source_id: "xK8p",        // From setup response
  terms: ["auth", "deploy"],          // Search terms (text or status, OR logic)
  statuses: ["To Do"],      // Filter by status
  ids: ["m3Qw", "p9Lx"]     // Filter by specific task IDs
})
// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]

タスクのステータスを更新：

tasks_update({
  source_id: "xK8p",        // From setup response
  ids: ["m3Qw", "p9Lx"],    // Task IDs from add/search responses
  status: "Done"            // Use "Deleted" to remove
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}

概要を取得：

tasks_summary({
  source_id: "xK8p"         // From setup response
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]}

🎛️ 環境変数

変数	デフォルト	説明
TRANSPORT	stdio	トランスポートモード：stdio または http
PORT	4680	HTTP サーバーのポート（TRANSPORT=http の場合）
PREFIX_TOOLS	true	ツール名に tasks_ を付けます
STATUS_WIP	In Progress	進行中ステータス名
STATUS_TODO	To Do	未着手ステータス名
STATUS_DONE	Done	完了ステータス名
STATUS_REMINDERS	Reminders	AI 向けのリマインダー（無効にするには空文字列を指定）
STATUS_NOTES	Notes	メモ／実行対象外のタスク（無効にするには空文字列を指定）
STATUSES	Backlog	カンマ区切りで追加するステータス
AUTO_WIP	true	WIPが1件ある場合は残りをTo Doに移動し、WIPがない場合は最初のTo DoをWIPに移動します
KEEP_DELETED	true	削除したタスクを保持します（AI がタスクを失うことはありません！）
INSTRUCTIONS	...	AI が従う指示をすべてのツール応答に含めます
SOURCES_PATH	./sources.json	ソースレジストリを保存するファイル（内部用）
DEBUG	false	true の場合、tasks_debug ツールを有効にします

詳細設定の例

任意で、WIP／ToDo／Doneのステータスを含めて順序を制御できます。

カスタムワークフローステータス：

{
  "env": {
    "STATUSES": "WIP,Pending,Archived,Done,To Review",
    "STATUS_WIP": "WIP",
    "STATUS_TODO": "Pending",
    "AUTO_WIP": "false"
  }
}

📊 ファイル形式

Markdown（.md）- 人が読みやすい形式

# Tasks - File Name

## In Progress
- [ ] Write user registration

## To Do
- [ ] Implement authentication
- [ ] Set up CI/CD pipeline

## Backlog
- [ ] Plan architecture
- [ ] Design database schema

## Done
- [x] Set up project structure
- [x] Initialize repository

## Reminders
- [ ] Don't move to Done until you verified it works
- [ ] After you move to Done, commit all the changes, use the task name as the commit message

## Notes
- [ ] The task tools were really great to use!

JSON（.json）- 構造化データ

{
  "groups": {
    "In Progress": [
      "Write user registration"
    ],
    "To Do": [
      "Implement authentication",
      "Set up CI/CD pipeline"
    ],
    "Backlog": [
      "Plan architecture",
      "Design database schema"
    ],
    "Done": [
      "Set up project structure",
      "Initialize repository"
    ],
    "Reminders": [
      "Don't move to Done until you verified it works",
      "After you move to Done, commit all the changes, use the task name as the commit message"
    ],
    "Notes": [
      "The task tools were really great to use!"
    ]
  }
}

YAML（.yml）- 設定に適した形式

groups:
  "In Progress":
    - Write user registration
  "To Do":
    - Implement authentication
    - Set up CI/CD pipeline
  Backlog:
    - Plan architecture
    - Design database schema
  Done:
    - Set up project structure
    - Initialize repository
  Reminders:
    - Don't move to Done until you verified it works
    - After you move to Done, commit all the changes, use the task name as the commit message

🖥️ サーバーの使用方法

# Show help
mcp-tasks --help

# Default: stdio transport
mcp-tasks

# HTTP transport
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks

# Custom configuration
STATUS_WIP="Working" AUTO_WIP=false mcp-tasks

💻 CLI の使用方法

すばやくタスクを管理するコマンドラインツールとして、mcp-tasks（または npx mcp-tasks）も使用できます。

# Setup a task file
mcp-tasks setup tasks.md $PWD                      # Setup with workspace

# Add tasks
mcp-tasks add "Implement authentication"           # Defaults to "To Do" status
mcp-tasks add "Write tests" "Backlog"              # Add with specific status
mcp-tasks add "Fix critical bug" "In Progress" 0   # Add at top (index 0)

# Search tasks
mcp-tasks search                                    # All tasks
mcp-tasks search "" "auth,login"                   # Search for specific terms
mcp-tasks search "To Do,Done" ""                   # Filter by statuses
mcp-tasks search "In Progress" "bug"               # Filter by status and search terms

# Update task status (comma-separated IDs)
mcp-tasks update m3Qw,p9Lx Done

# Get summary
mcp-tasks summary

# Add a reminder (feature must be enabled with REMINDERS=true)
mcp-tasks add "Don't move to Done until you verified it works" Reminders

CLI の機能：

• すべての MCP ツール機能に直接アクセスできます
• 解析やスクリプトで扱いやすい JSON 出力
• MCP ツールと同等の信頼性と重複防止機能
• 自動化スクリプトや CI/CD パイプラインに最適です

🧪 開発

# Clone and setup
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install

# Development mode (auto-restart)
npm run dev              # STDIO transport
npm run dev:http         # HTTP transport on port 4680

# Build and test
npm run build           # Compile TypeScript
npm run lint            # Check code style
npm run lint:full       # Build + lint

🛠️ トラブルシューティング

要件

• Node.js ≥20 - このパッケージにはバージョン20以上の Node.js が必要です

よくある問題

npx-tasks の実行時に発生する ERR_MODULE_NOT_FOUND

• 問題：npx mcp-tasks の実行時に Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' のようなエラーが発生します
• 原因：npx キャッシュが破損しているか不完全なため、依存関係を正しく解決できません
• 解決策：npx キャッシュをクリアして、もう一度お試しください：

  npx clear-npx-cache
  npx mcp-tasks
  

• 注記：この問題は Node.js v20 と v22 の両方で発生することがあり、キャッシュをクリアすると解決します

タスクはどこに保存されていますか？

• タスクは、AI が tasks_setup で指定したファイルパスに保存されます
• 絶対パスは、すべてのツール呼び出しの応答で source.path の下に返されます
• 場所を忘れた場合は、任意のツールの応答を確認するか、AI に表示するよう依頼してください

Markdown ファイルの内容が失われる：

• ⚠️ ツールはファイル全体を書き換え、認識されるステータスセクション内のタスクのみを保持します
• タスク以外のコンテンツ（メモやドキュメント）は、ツールがファイルを変更すると失われる場合があります
• タスクを他のコンテンツと混在させず、専用のタスクファイルを使用してください

AI にタスクファイルを直接編集させないのはなぜですか？

• ファイル解析の複雑さ： AI はファイル全体を読み込み、Markdown の構造を解析して現在の状態を把握する必要があり、コストがかかるうえ、エラーも発生しやすくなります
• 複数ステップの操作： タスクを「進行中」から「完了」に移すには、正しいセクションを特定して変更するために、複数の read_file、grep_search、sed の呼び出しが必要です
• コンテキストの喪失： 大きなタスクファイルでは、トークンの制限によって不完全な断片を扱うことになり、全体の構造を見失う可能性があります
• 状態の把握： ファイルの断片的なセクションを読むだけでは、プロジェクトの実際の状態を把握するのが困難です。実際に進行中のタスクはどれでしょうか？
• 編集の正確性： 手動編集では、Markdown の書式が壊れたり、タスクが失われたり、誤って別のセクションが変更されたりするおそれがあります
• 同時編集の競合： AI がファイルを直接編集すると、競合や上書きを起こさずに人間が安全に手動変更することができません
• トークン効率の悪さ： 読み込み・解析・編集を繰り返すより、入出力が明確な構造化されたツール呼び出しのほうが、消費するトークンを大幅に抑えられます
• 安全性： AI がファイルを直接編集すると、誤ってタスクを変更または削除する可能性がありますが、これらのツールを使えばタスクを書き換えたり削除したりすることはできません

🤝 貢献

貢献を歓迎します！次の手順に従ってください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature-name
3. テストを追加して変更を加えます
4. 次を実行します：npm run lint:full
5. プルリクエストを送信します

📄 ライセンス

MIT ライセンスです。詳細は LICENSE をご覧ください。

🔗 リンク

• 📦 NPM パッケージ
• 🐙 GitHub リポジトリ
• 🐛 問題を報告
• 📚 MCP 仕様
• ⚡ FastMCP フレームワーク