todoist-v1-mcp-server

Todoistのためのクリーンで信頼性の高いMCP（Model Context Protocol）サーバー — Todoist unified API v1に基づいて構築されています。

なぜこれが必要なのか

公式のTodoist web MCP (todoist-ai) には、Anthropic側で毎日再接続が必要になるという既知の永続的な切断バグがあります。コミュニティによる代替案は、非推奨のREST API v2に基づいて構築されているか、TodoistのAPIが進化して新しいフィールドが追加された際に失敗を引き起こすスキーマ検証のバグを抱えています。

このサーバーの特徴：

• 現在のTodoist API v1をターゲットにしています（非推奨のv2ではありません）

• stdioトランスポートを使用 — クラウドへの依存や毎日の再接続は不要です

• 最新のMCP SDK registerTool() APIを使用（非推奨の setRequestHandler パターンではありません）

• APIレスポンスに対して厳格な出力スキーマを強制しません — Todoistが新しいフィールドを追加しても、何も壊れることなく動作します

• SDKラッパーへの依存ゼロ — axiosを介した直接的なHTTP呼び出しを行うため、APIから乖離する中間ライブラリが存在しません

ツール（合計20個）

タスク

プロジェクト

セクション

ラベル

セットアップ

1. Todoist APIトークンの取得

Todoist → 設定 → 連携機能 → 開発者 に移動し、APIトークンをコピーします。

2. インストールとビルド

git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build

3. Claude Desktopの設定

~/Library/Application Support/Claude/claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Claude Desktopを再起動します。接続されたMCPサーバーに「todoist」が表示されるはずです。

4. Claude Codeの設定（オプション）

claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js

次に環境変数を設定します：

export TODOIST_API_TOKEN=your_api_token_here

または、シェルプロファイルに追加してください。

使用例

接続後、Claudeは以下のような自然言語を処理できます：

• "今日の予定は？" → filter: "today" を指定して todoist_get_tasks を使用

• "来週の火曜日に歯医者に行くタスクを追加して" → todoist_create_task を使用

• "歯医者のタスクを完了にして" → todoist_complete_task を使用

• "期限切れのタスクをすべて見せて" → filter: "overdue" を指定して todoist_get_tasks を使用

• "Home Renovationというプロジェクトを作成して" → todoist_create_project を使用

• "どんなプロジェクトがある？" → todoist_get_projects を使用

Todoistフィルタ構文

todoist_get_tasks の filter パラメータは、Todoistの完全な自然言語フィルタ構文をサポートしています：

フィルタの完全なドキュメント: https://todoist.com/help/articles/introduction-to-filters

要件

• Node.js 18以上

• Todoistアカウント（無料プランでも動作します）

開発

npm run dev   # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start     # run compiled server

テスト

テストスイートは実際のTodoist APIにアクセスし、タスク、プロジェクト、セクション、ラベル全体で完全なCRUDサイクルを実行します。すべてのテストデータには [mcp-test] というプレフィックスが付き、自動的にクリーンアップされます。

TODOIST_API_TOKEN=your_token npm test

APIトークンは Todoist → 設定 → 連携機能 → 開発者 にあります。これは claude_desktop_config.json に入力したものと同じトークンです。

コントリビューション

プルリクエストを歓迎します。目標は、Todoist API v1の最新状態を維持する、最小限で正確な実装です。優先事項：

1. 巧妙さよりも正確さ

2. 寛容な出力処理（未知のAPIフィールドを拒否しない）

3. 何が問題でどう修正すべきかを伝える役立つエラーメッセージ

ライセンス

MIT