MCP-Todoist Integration

MCP-Todoist 連携

このプロジェクトは、Todoist と連携する Model Context Protocol（MCP） サーバーを提供し、言語モデルが Todoist のタスクやプロジェクトを操作できるようにします。

機能

• Todoist API との完全な連携
• タスク、プロジェクト、セクション、ラベル、コメントの作成、読み取り、更新、削除
• プロジェクトの共同作業者へのアクセス
• さまざまな条件でタスクをフィルタリング
• 言語モデルで使用するための、十分なドキュメントが用意されたツールとリソース

要件

• Python 3.10 以降
• API トークンを持つ Todoist アカウント
• MCP 対応クライアント（Claude Desktop など）

Claude Desktop での使用方法

この MCP サーバーを Claude Desktop で使用するには、2 つの方法があります。

オプション 1：uvx を使用（推奨）

1. uvx を使用してパッケージをインストールします：

   uvx install mcp-todoist
   

2. Claude Desktop の MCP 設定にサーバーを追加します：

   • Claude Desktop を開きます
   • Settings > Advanced に移動します
   • 「MCP Servers Configuration」で、JSON 設定に追加します：

     "mcpServers": {
       "todoist": {
         "command": "uvx",
         "args": ["mcp-todoist"],
         "env": {
           "TODOIST_API_TOKEN": "your_todoist_api_token_here"
         }
       }
     }
     

オプション 2：クローンしたリポジトリを使用

1. リポジトリをクローンし、開発モードでパッケージをインストールします：

   git clone https://github.com/your-username/mcp-todoist.git
   cd mcp-todoist
   pip install -e .
   

2. Claude Desktop の MCP 設定にサーバーを追加します：

   • Claude Desktop を開きます
   • Settings > Advanced に移動します
   • 「MCP Servers Configuration」で、JSON 設定に追加します：

     "mcpServers": {
       "todoist": {
         "command": "python",
         "args": ["/full/path/to/mcp-todoist/main.py"],
         "env": {
           "TODOIST_API_TOKEN": "your_todoist_api_token_here"
         }
       }
     }
     

オプション 3：uv を使用

uv は高速な Python パッケージインストーラー兼リゾルバーです。このプロジェクトで使用するには、次の手順に従います：

1. まず、uv がインストールされていることを確認します：

   # Install uv (if you haven't already)
   brew install uv  # On macOS with Homebrew
   pipx install uv  # Or use pipx
   

2. リポジトリをクローンします：

   git clone https://github.com/your-username/mcp-todoist.git
   cd mcp-todoist
   

3. ロックファイルを作成して維持します：

   # Create/update the lock file (do this when dependencies change)
   uv pip sync requirements.txt
   

4. uv を使用して MCP サーバーを実行します：

   uv run mcp dev main.py
   

5. Claude Desktop を設定します：

   "mcpServers": {
     "todoist": {
       "command": "uv",
       "args": ["run", "mcp", "dev", "/full/path/to/mcp-todoist/main.py"],
       "env": {
         "TODOIST_API_TOKEN": "your_todoist_api_token_here"
       }
     }
   }
   

6. 設定を保存して Claude Desktop を再起動します

7. Claude に Todoist を使用するよう依頼すると、Claude との会話で Todoist MCP サーバーにアクセスできます

Todoist API トークンの取得

Todoist API トークンを取得するには：

1. Todoist アカウントにログインします
2. Settings > Integrations に移動します
3. 「API token」セクションから API トークンをコピーします

インストール

ソースからパッケージをインストールする場合：

1. このリポジトリをクローンします：

   git clone https://github.com/your-username/mcp-todoist.git
   cd mcp-todoist
   

2. 依存関係をインストールします：

   pip install -r requirements.txt
   

3. Todoist API トークンを記載した .env ファイルを作成します：

   cp .env.example .env
   # Edit .env file to add your Todoist API token
   

MCP Dev Tools での実行

テストと開発には、MCP dev tools を使用します：

mcp run main.py

これにより MCP サーバーが起動し、対話形式でテストできるようになります。

視覚的に操作するために MCP Inspector を使用して実行するには：

mcp dev main.py

利用可能なツール

次の Todoist ツールを利用できます：

タスク管理

• create_task - タイトル、期限、プロジェクトなどを指定して新しいタスクを作成します
• get_tasks - フィルターに基づいてタスクを取得します
• get_task - ID を指定して特定のタスクを取得します
• update_task - 既存のタスクを更新します
• complete_task - タスクを完了としてマークします
• uncomplete_task - 完了済みのタスクを未完了としてマークします
• delete_task - タスクを削除します

プロジェクト管理

• get_projects - すべてのプロジェクトを取得します
• get_project - ID を指定して特定のプロジェクトを取得します
• add_project - 新しいプロジェクトを作成します
• update_project - 既存のプロジェクトを更新します
• delete_project - プロジェクトを削除します
• archive_project - プロジェクトをアーカイブします
• unarchive_project - プロジェクトのアーカイブを解除します

セクション管理

• get_sections - プロジェクト内のすべてのセクションを取得します
• get_section - ID を指定して特定のセクションを取得します
• add_section - 新しいセクションを作成します
• update_section - 既存のセクションを更新します
• delete_section - セクションを削除します

ラベル管理

• get_labels - すべてのラベルを取得
• get_label - ID を指定して特定のラベルを取得
• add_label - 新しいラベルを作成
• update_label - 既存のラベルを更新
• delete_label - ラベルを削除

コメント管理

• get_comments - タスクまたはプロジェクトのコメントを取得
• get_comment - ID を指定して特定のコメントを取得
• add_comment - タスクまたはプロジェクトにコメントを追加
• update_comment - 既存のコメントを更新
• delete_comment - コメントを削除

コラボレーション

• get_collaborators - プロジェクトのコラボレーターを取得

利用可能なリソース

以下の Todoist リソースを利用できます。

• todoist://tasks - すべてのタスク
• todoist://tasks/project/{project_id} - 特定のプロジェクトのタスク
• todoist://tasks/section/{section_id} - 特定のセクションのタスク
• todoist://tasks/label/{label} - 特定のラベルが付いたタスク
• todoist://projects - すべてのプロジェクト
• todoist://sections/{project_id} - 特定のプロジェクトのセクション
• todoist://labels - すべてのラベル

使用例

タスクの作成

Please create a new task in Todoist called "Buy groceries" due tomorrow.

プロジェクトのタスクの取得

Show me all tasks in my "Work" project.

タスクの完了

Mark the "Buy groceries" task as complete.

タスクへのコメントの追加

Add a comment to the task with ID "12345678" saying "Don't forget milk and eggs".

セクションを含む新しいプロジェクトの作成

Create a new project called "Home Renovation" and add sections for "Kitchen", "Bathroom", and "Living Room".

開発

プロジェクトに貢献する場合や、用途に合わせて変更する場合は、次の手順に従ってください。

1. リポジトリをフォークします
2. 変更を加えます
3. mcp run main.py または mcp dev main.py でテストします
4. プルリクエストを送信します

開発での uv の使用

このプロジェクトでは、依存関係の管理と実行を高速化するために uv を使用できます。

1. 依存関係が変更された場合は、ロックファイルを作成または更新します。

   uv pip sync requirements.txt
   

2. uv でアプリケーションを実行します。

   uv run mcp dev main.py
   

3. ロックファイルに問題が発生した場合は、次の方法でトラブルシューティングできます。

   # Remove the lock file and regenerate it
   rm uv.lock
   uv pip sync requirements.txt
   
   # Or run without using the lock file (temporary solution)
   UV_LOCK=0 uv run mcp dev main.py
   

Git フック

このプロジェクトでは、コードの品質と一貫性を保つために pre-commit フックを使用しています。

1. 開発用の依存関係をインストールします。

   pip install -e ".[dev]"
   

2. git フックをインストールします。

   pre-commit install
   

3. これで、コミットするたびにフックが実行されます。

   • コードフォーマットには Black
   • インポートの並べ替えには isort
   • リンティングには flake8
   • 各種ファイルチェック（末尾の空白、YAML の検証など）

フックが失敗すると、コミットは中止されます。問題を修正して、もう一度お試しください。

すべてのファイルに対して、フックを手動で実行することもできます。

pre-commit run --all-files

PyPI への公開

このプロジェクトでは、git タグに基づく自動バージョン管理に setuptools_scm を使用しています。

1. すべてのテストがローカルで合格することを確認します。

   pip install -e ".[dev]"
   flake8 . --exclude=.venv,venv,env
   black --check .
   isort --check-only --profile black .
   pytest
   

2. セマンティックバージョニング（「v」接頭辞なし）で新しいリリースを作成します。

   # For a new version (e.g., 0.1.0)
   git tag 0.1.0
   git push origin 0.1.0
   

3. GitHub Actions のワークフローによって、次の処理が自動的に実行されます。

   • テストの実行
   • PR とコミットからの変更履歴の生成
   • 変更履歴を含む GitHub リリースの作成
   • パッケージのビルドと PyPI への公開

4. 手動で公開する場合（必要に応じて）。

   pip install build twine
   python -m build
   twine check dist/*
   twine upload --repository-url https://test.pypi.org/legacy/ dist/*  # Test first
   twine upload dist/*  # Then to production PyPI
   

5. 代替方法：ワークフローを手動で実行します。

   • GitHub リポジトリで「Actions」→「Build and Publish」ワークフローに移動します
   • 「Run workflow」をクリックします
   • Test PyPI の場合は「test」を、本番 PyPI の場合は「prod」を選択します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。