todoist-mcp

Todoist MCP サーバー

Todoist のタスク管理用 Model Context Protocol（MCP）サーバーです。Claude が Todoist のタスクやプロジェクトを操作できます。

機能

• ✅ タスクの作成、読み取り、更新、完了
• 📋 高度なフィルタリングによるタスクの一覧表示
• 🔍 テキスト内容によるタスクの検索
• 📁 プロジェクトの管理
• 🏷️ ラベルと優先度に対応
• 📅 自然言語の日付解析
• ⚡ API の制限内に収めるためのレート制限
• 🛡️ 包括的なエラー処理

インストール

前提条件

• Node.js >= 18.0.0
• npm または yarn
• API トークンを取得済みの Todoist アカウント

ソースからのインストール

# Clone the repository
git clone <your-repo-url>
cd todoist-mcp

# Install dependencies
npm install

# Build the project
npm run build

設定

1. Todoist API トークンを取得する

1. Todoist の連携設定に移動します
2. 「API token」セクションまでスクロールします
3. 個人用 API トークンをコピーします

2. 環境変数を設定する

プロジェクトのルートに .env ファイルを作成します。

cp .env.example .env

.env を編集し、Todoist API トークンを追加します。

TODOIST_API_TOKEN=your_actual_token_here
LOG_LEVEL=error

3. Claude Desktop を設定する

Claude Desktop の設定ファイルにサーバーを追加します。

場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

設定：

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-mcp/build/server.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_actual_token_here"
      }
    }
  }
}

重要： /absolute/path/to/todoist-mcp をプロジェクトディレクトリの実際の絶対パスに置き換えてください。

4. Claude Desktop を再起動する

設定を更新した後、変更を反映するために Claude Desktop を再起動します。

利用可能なツール

todoist_create_task

プロジェクト、期限、優先度、ラベル、サブタスクの親タスクを指定して、Todoist に新しいタスクを作成します。これらの指定は任意です。

パラメーター：

• content（必須）：タスクの内容／タイトル
• description（任意）：タスクの説明
• project_id（任意）：タスクを追加するプロジェクトの ID
• section_id（任意）：プロジェクト内のセクション ID
• due_date（任意）：自然言語または YYYY-MM-DD 形式の期限
• priority（任意）：優先度：1（通常）、2（中）、3（高）、4（緊急）
• labels（任意）：ラベル名の配列
• parent_id（任意）：サブタスクを作成する親タスクの ID
• parent_task_name（任意）：検索する親タスク名（parent_id の代替）

例：

Create a task "Write report" due tomorrow with high priority
Create a task "Buy groceries" in the Shopping project
Create a task "Team meeting" due "next Monday at 2pm"
Create a subtask "Buy milk" under parent task "Go to the supermarket"
Create a subtask "Review slides" under task 8237492837
Add subtask "Call John" to the task "Prepare presentation"

todoist_list_tasks

プロジェクト、セクション、ラベル、またはカスタム Todoist フィルターを指定して、アクティブなタスクを一覧表示します。各フィルターの指定は任意です。

パラメーター：

• project_id（任意）：プロジェクト ID で絞り込み
• section_id（任意）：セクション ID で絞り込み
• label（任意）：ラベル名で絞り込み
• filter（任意）：Todoist のフィルタークエリ（例：「today」、「overdue」、「p1」）
• limit（任意）：返すタスクの最大数（デフォルト：50、最大：200）

例：

List all my tasks
List tasks in project "Work"
List tasks due today
List all overdue tasks with limit 20

todoist_get_task

指定したタスクのメタデータをすべて含む詳細情報を取得します。

パラメーター：

• task_id（必須）：取得するタスクの ID

例：

Get details for task 123456789
Show me task 987654321

todoist_update_task

タスクの内容、説明、期限、優先度、またはラベルを更新します。

パラメーター：

• task_id（必須）：更新するタスクの ID
• content（任意）：新しいタスクの内容
• description（任意）：新しいタスクの説明
• due_date（任意）：新しい期限（自然言語または YYYY-MM-DD）
• priority（任意）：新しい優先度（1～4）
• labels（任意）：新しいラベルの配列

例：

Update task 123 to have priority 4
Change task 456 due date to "next Friday"
Update task 789 content to "Revised meeting agenda"

todoist_complete_task

タスクを完了済みとしてマークします。

パラメーター：

• task_id（必須）：完了するタスクの ID

例：

Complete task 123456
Mark task 789012 as done

todoist_list_projects

受信トレイや共有プロジェクトを含む、Todoist のすべてのプロジェクトを一覧表示します。

パラメーター： なし

例：

List all my projects
Show me all my Todoist projects

todoist_search_tasks

タスクの内容または説明に含まれるテキストでタスクを検索します。

パラメーター：

• query（必須）：タスクの内容と説明から検索するテキスト
• limit（任意）：返すタスクの最大数（デフォルト：50、最大：200）

例：

Search for tasks containing "meeting"
Find all tasks with "budget" in them

開発

ビルド

npm run build

開発モード（監視）

npm run dev

テストを実行する

npm test

監視モードでテストを実行する

npm run test:watch

レート制限

このサーバーは、Todoist の API レート制限である15 分あたり 450 リクエストを遵守します。上限を超えると、API は 429 エラーを返します。このエラーは捕捉され、わかりやすいエラーメッセージとともに報告されます。しばらく待ってからリクエストを再試行できます。

エラー処理

すべてのエラーは、内容を説明するメッセージとともに返されます。よくあるエラーは次のとおりです。

• 無効な API トークン：.env の設定または Claude Desktop の設定を確認してください
• タスクが見つかりません：タスク ID が存在し、削除されていないことを確認してください
• レート制限を超過しました：15 分待つか、リクエストの頻度を下げてください
• ネットワークエラー：インターネット接続を確認してください
• 検証エラー：ツールに渡しているパラメーターを確認してください

自然言語による日付の指定

このサーバーは、Todoist の自然言語による日付解析に対応しています。次のようなフレーズを使用できます。

• "tomorrow"
• "next Monday"
• "every Friday"
• "in 3 days"
• "next week"
• "Dec 25"

標準的な日付形式も使用できます。

• "2024-12-31"
• "2024-12-31T14:30:00"

プロジェクト構成

todoist-mcp/
├── src/
│   ├── server.ts           # Main MCP server entry point
│   ├── types/              # TypeScript type definitions
│   ├── api/                # Todoist API client and errors
│   ├── tools/              # MCP tool implementations
│   └── utils/              # Utilities (logger, rate limiter)
├── tests/
│   └── unit/               # Unit tests
├── build/                  # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

公開とレジストリ

• MCP 名： io.github.ecfaria/todoist-mcp
• NPM パッケージ： @ecfaria/todoist-mcp-server
• server.json： レジストリの定義については、このリポジトリのルートを参照してください

公開手順

1. 必要に応じてバージョン番号を更新します（npm version <patch|minor|major>）。
2. 配布用ファイルをビルドします：npm run build。
3. npm に公開します：npm publish --access public（スコープ付きパッケージはデフォルトで非公開です）。
4. レジストリのメタデータを検証します：mcp-publisher validate。
5. MCP レジストリに公開します：mcp-publisher publish。

リリースノート（v1.0.0）

• レジストリのメタデータ（mcpName）を package.json に追加しました。
• 公開手順とレジストリ上の識別情報を文書化しました。
• レジストリへの公開に使用する正式な server.json の参照先を導入しました。
• 名前の衝突を避けるため、スコープ付き npm パッケージ名 @ecfaria/todoist-mcp-server を採用しました。

トラブルシューティング

Claude にサーバーが表示されない

1. claude_desktop_config.json に記載されているパスが絶対パスであり、正しいことを確認します
2. プロジェクトをビルドしたことを確認します（npm run build）
3. 設定に API トークンが指定されていることを確認します
4. Claude Desktop を完全に再起動します

API トークンが無効

1. Todoist の連携設定に移動します
2. 新しい API トークンを生成します
3. .env ファイルまたは Claude Desktop の設定を更新します
4. サーバーまたは Claude Desktop を再起動します

タスクが表示されない

1. 正しいプロジェクト ID またはフィルターを使用していることを確認します
2. タスクがすでに完了済みでないことを確認します
3. フィルターを使わずにすべてのタスクを一覧表示し、どのタスクがあるか確認します

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

MIT

サポート

• Todoist API ドキュメント
• MCP ドキュメント
• GitHub の課題

謝辞

以下を使用して構築しました：

• Model Context Protocol SDK
• Todoist REST API v2
• TypeScript
• Zod