Todoist MCP Server

Todoist MCP サーバー

Claude と Todoist を接続し、自然言語でタスクとプロジェクトを包括的に管理できる MCP（Model Context Protocol）サーバーです。

インストール

Claude Desktop（ワンクリックインストール）

1. 最新のリリースから todoist-mcp.mcpb をダウンロードします
2. ファイルをダブルクリックします（または Claude Desktop にドラッグします）
3. 求められたら、Todoist API トークンを入力します
4. チャットを開始します：「Todoist のプロジェクトを表示して」

Claude Code ／その他の MCP クライアント

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

機能

• 19 個の MCP ツールで Todoist を包括的に管理
• タスク管理：優先度、期限、ラベルを設定したタスクの作成、更新、削除、完了、再開
• 一括操作：複数のタスクを効率的に処理
• サブタスク：完了状況の追跡に対応した階層型のタスク管理
• プロジェクトとセクション：組織化を全面的にサポート
• ラベル、フィルター、リマインダー：Pro／Business の機能に対応
• 自然言語：Todoist の自然言語解析を使ったクイック追加
• ドライランモード：変更を加えずに操作をテスト

ドライランモード

ドライランモードを使うと、Todoist ワークスペースに実際の変更を加えずに、操作や自動化をテストできます。実際に実行する前に、テスト、デバッグ、API の学習、自動化スクリプトの検証を行うのに最適です。

ドライランモードを有効にする方法

環境設定に DRYRUN=true を追加します：

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

ドライランモードの動作

• 操作を検証：実際の API データを使い、操作が成功するかを検証します
• 変更をシミュレート：作成、更新、削除、完了の操作をシミュレートし、実行しません
• 実データを照会：読み取り操作（タスク、プロジェクト、ラベルの取得）では実際の API を使用します
• 詳細なログ：何が行われるかを [DRY-RUN] のプレフィックス付きで明確に表示します
• エラーを検出：実際に実行した場合と同じエラーを検出します

使用例

• 自動化のテスト：複雑な一括操作を実行前に検証
• API の学習：意図しない変更を加える心配なく機能を試す
• 問題のデバッグ：実行される操作を把握
• 安全な試行：実際のタスクに影響を与えずに新しいワークフローを試す
• トレーニングとデモ：実データを変更せずに操作の動作を説明

使用例

ドライランモードを有効にすると、操作によって何が行われるかが表示されます：

You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)

対応する操作

19 個すべての MCP ツールがドライランモードに対応しています：

• タスクの作成、更新、完了、削除
• サブタスクの操作と階層の変更
• 複数のタスクに対する一括操作
• プロジェクトとセクションの作成
• ラベルの管理操作
• リマインダーの CRUD 操作
• コメントの作成

ドライランモードを無効にする

DRYRUN 環境変数を削除するか、false に設定してから、Claude Desktop を再起動すると通常の動作モードに戻ります。

ツールの概要

サーバーは、Todoist を完全に管理するための 19 個の MCP ツールを提供します。

パラメーターと例を含むツールの詳細なドキュメントについては、TOOLS_REFERENCE.md を参照してください。

トラブルシューティング

よくある問題

「Todoist プロジェクトが見つかりません」または接続エラー：

• API トークンが正しいことを確認してください
• トークンが claude_desktop_config.json に正しく設定されていることを確認してください
• トークンの前後に余分なスペースや引用符がないことを確認してください

MCP サーバーが読み込まれない：

• パッケージがグローバルにインストールされていることを確認してください：npm list -g @greirson/mcp-todoist
• Claude Desktop を完全に再起動してください
• お使いのオペレーティングシステムに対応する設定ファイルのパスが正しいことを確認してください
• mcp-todoist バイナリのフルパスを試してください：/Users/USERNAME/.npm-global/bin/mcp-todoist

権限エラー：

• macOS/Linux では、設定ディレクトリの作成が必要な場合があります：mkdir -p ~/.config
• Claude Desktop に設定ファイルの読み取り権限があることを確認してください

使用例

プロジェクトとセクションの設定

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

タスクの作成と管理

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

クイック追加

Quick Add ツールは Todoist アプリのように自然言語のテキストを解析し、1 つのコマンドで複数の機能をサポートします。

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

クイック追加の構文：

• 期日：「tomorrow」「next Friday」「Jan 23」「in 3 days」のような自然言語の日付
• プロジェクト：#ProjectName（プロジェクト名にスペースは使用できません）
• ラベル：@label（例：「@urgent」「@work」）
• 担当者：+name（共有プロジェクトの場合）
• 優先度：p1（緊急）、p2、p3、p4（最低）
• 期限：{in 3 days} または {March 15}
• 説明：//your description here（末尾に指定する必要があります）

サブタスクの管理

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

一括操作

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

コメントの管理

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

ラベルの管理

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

リマインダーの管理（Pro/Business）

"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"

タスクの検索

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

テストと検証

"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"

ドライランテスト

ドライランモードが有効（DRYRUN=true）な場合は、通常のコマンドを使用してください。自動的にシミュレーションされます。

"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"

これらの操作はすべて実際のデータに対して検証されますが、変更は行われません。

開発

ソースからのビルド

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

開発コマンド

# Watch for changes and rebuild
npm run watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

アーキテクチャ

このコードベースは、保守性と拡張性を考慮して設計された、明快でモジュール化されたアーキテクチャを採用しています。

コア構成

• src/index.ts：リクエストルーティングを行うメインサーバーのエントリーポイント
• src/types.ts：TypeScript の型定義とインターフェース
• src/type-guards.ts：実行時の型検証関数
• src/validation.ts：入力の検証とサニタイズ
• src/errors.ts：構造化された処理を備えたカスタムエラー型
• src/cache.ts：パフォーマンス最適化のためのインメモリーキャッシュ

モジュール化されたツール構成

• src/tools/：機能ごとに整理された、ドメイン固有の MCP ツール定義：
  • task-tools.ts - タスク管理（9 個のツール）
  • subtask-tools.ts - サブタスク操作（5 個のツール）
  • project-tools.ts - プロジェクト／セクション管理（4 個のツール）
  • comment-tools.ts - コメント操作（2 個のツール）
  • label-tools.ts - ラベル管理（5 個のツール）
  • reminder-tools.ts - リマインダー操作（4 個のツール）
  • test-tools.ts - テストと検証（3 個のツール）
  • index.ts - エクスポートの一元管理

ビジネスロジックのハンドラー

• src/handlers/：ドメインごとに分離されたビジネスロジックモジュール：
  • task-handlers.ts - タスクの CRUD と一括操作
  • subtask-handlers.ts - 階層型タスクの管理
  • project-handlers.ts - プロジェクトとセクションの操作
  • comment-handlers.ts - コメントの作成と取得
  • label-handlers.ts - ラベルの CRUD と統計
  • reminder-handlers.ts - Sync API によるリマインダーの CRUD
  • test-handlers.ts - API テスト基盤
  • test-handlers-enhanced/ - 包括的な CRUD テストフレームワーク

ユーティリティモジュール

• src/utils/：共有ユーティリティ関数：
  • api-helpers.ts - API レスポンス処理ユーティリティ
  • error-handling.ts - エラー管理の一元化
  • parameter-transformer.ts - MCP から Todoist SDK のパラメーター形式への変換
  • dry-run-wrapper.ts - ドライランモードの実装

変更履歴

すべての変更の詳細な履歴については、CHANGELOG.md を参照してください。

移行ガイドと破壊的変更については、完全な変更履歴を参照してください。

コントリビューション

コントリビューションを歓迎します！このプロジェクトは活発に保守されており、改善に関心を寄せてくださるコミュニティの皆さんに感謝しています。

AI 支援によるコントリビューションについて

私は自身の開発ワークフローの一環として Claude Code を使用しています。AI 支援によるコーディングは、このプロジェクトの開発において一般的なものです。コントリビューターの皆さんにも、AI コーディングアシスタントを含め、生産性を高めるあらゆるツールの利用を推奨します。

ただし、AI ツールを使うと、一見正しそうでも、API マッピングの誤り、パフォーマンスの低下、互換性を損なう型変更、無関係な機能をまとめて追加するスコープの拡大など、微妙な問題を引き起こすコードを大量に生成しやすくなります。API パス自体が変わったことに気づかず URL プレフィックスだけを置き換えたり、limit パラメーターを維持せず毎回すべてのページを取得してページネーションを追加したりする PR を見たことがあります。

このため、すべての PR に対して、アーキテクチャ面を含む徹底的なレビューを行います。これは門前払いをするためではなく、多くの人が MCP クライアントを通じて依存しているコードベースを維持するためです。レビューされていないように見える AI 生成の出力を含む PR には、何をなぜ変更する必要があるのか、詳細なフィードバックをお送りします。内容を学んだうえで、再提出してください。

PR の要件

プルリクエストを提出する前に、次の点を確認してください。

1. **1 つの PR につき、懸念事項は 1 つにしてください。**バグ修正は 1 つの PR、新機能は別の PR、ドキュメントの更新も別の PR にします。無関係な機能にまたがって差分が 40 ファイル以上に及ぶ場合は、分割が必要です。スコープが混在する PR は、分割のために差し戻します。

2. **自分のコードが何をするのか理解してください。**AI ツールが書いたコードであれば、提出前に批判的に読み直してください。それぞれの変更がなぜ必要なのか説明できますか？不具合が起きたときにデバッグできますか？できない場合は、まだ提出できる状態ではありません。

3. **テストを追加または更新してください。**新機能にはテストが必要です。バグ修正には、そのバグを検出できるテストが必要です。API エンドポイントを変更する場合は、実際の API に対して動作を検証してください。URL の置き換えだけで十分だと決めつけないでください。

4. **手動で検証してください。**ローカルで npm run build と npm test を実行してください。API 連携コードを変更する場合は、自分の Todoist アカウントでテストしてください（DRYRUN=true でドライランモードを利用できます）。検証した証拠を PR の説明に含めてください。

5. **CI を通過させてください。**CI チェックに失敗している PR は、すべて成功するまでレビューしません。

良い PR とは

• 何を、そしてなぜ変更するのかを説明する、明確で具体的なタイトルと本文
• レビューしやすい、焦点の絞られた差分（変更行数は 200 行未満が理想です）
• 変更が正しく動作することを示すテスト
• ユーザー向けの動作に影響する変更の場合は、更新されたドキュメント
• 無関係な書式変更、リファクタリング、「ついでに」行う改善を含まないこと

はじめに

1. リポジトリをフォークします
2. main からフィーチャーブランチを作成します
3. 上記のガイドラインに沿って変更を加えます
4. npm run build && npm test && npm run lint を実行して検証します
5. 明確な説明を添えて PR を提出します

変更が求められているかどうか、またはどのように進めるべきかが分からない場合は、まず issue を作成して相談してください。コードを書く前に全員の時間を節約し、適切な進め方について認識を合わせられます。

ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。詳細は LICENSE ファイルをご覧ください。

問題とサポート

問題が発生した場合やサポートが必要な場合は、GitHub repository で issue を登録してください。