TickTick MCP Server

TickTick MCP サーバー

TickTick の Model Context Protocol（MCP） サーバーです。Claude やその他の MCP クライアントから、TickTick のタスク管理システムを直接操作できます。

機能

• 📋 TickTick のすべてのプロジェクトとタスクを表示
• ✏️ 自然言語で新しいプロジェクトやタスクを作成
• 🔄 既存のタスクの詳細（タイトル、内容、日付、優先度）を更新
• ✅ タスクを完了としてマーク
• 🗑️ タスクやプロジェクトを削除
• 🔄 TickTick のオープン API と完全に連携
• 🔌 Claude やその他の MCP クライアントとシームレスに連携

前提条件

• Python 3.10 以降
• uv — 高速な Python パッケージインストーラーおよびリゾルバー
• API にアクセスできる TickTick アカウント
• TickTick API 認証情報（Client ID、Client Secret、Access Token）

インストール

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

   git clone https://github.com/jacepark12/ticktick-mcp.git
   cd ticktick-mcp
   

2. uv でインストールします：

   # Install uv if you don't have it already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create a virtual environment
   uv venv
   
   # Activate the virtual environment
   # On macOS/Linux:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate
   
   # Install the package
   uv pip install -e .
   

3. TickTick で認証します：

   # Run the authentication flow
   uv run -m ticktick_mcp.cli auth
   

   次の操作が行われます：

   • TickTick の Client ID と Client Secret の入力を求められます
   • TickTick にログインするためのブラウザーウィンドウが開きます
   • アクセストークンが .env ファイルに自動的に保存されます

4. 設定をテストします：

   uv run test_server.py
   

   これにより、TickTick の認証情報が正しく機能していることを確認できます。

TickTick での認証

このサーバーは OAuth2 を使用して TickTick と認証します。セットアップは簡単です。

1. TickTick Developer Center でアプリケーションを登録します

   • リダイレクト URI を http://localhost:8000/callback に設定します
   • Client ID と Client Secret を控えておきます

2. 認証コマンドを実行します：

   uv run -m ticktick_mcp.cli auth
   

3. プロンプトに従って Client ID と Client Secret を入力します

4. ブラウザーウィンドウが開き、TickTick アカウントを使ってアプリケーションを認証できます

5. 認証後、アプリケーションにリダイレクトされ、アクセストークンが .env ファイルに自動的に保存されます

サーバーがトークンを自動的に更新するため、アクセスを取り消すか .env ファイルを削除しない限り、再認証は不要です。

Dida365 での認証

滴答清单 - Dida365 は TickTick の中国版で、認証手順は TickTick と同様です。次の手順に従って Dida365 の認証を設定します。

1. Dida365 Developer Center でアプリケーションを登録します

   • リダイレクト URI を http://localhost:8000/callback に設定します
   • Client ID と Client Secret を控えておきます

2. .env ファイルに環境変数を追加します：

   TICKTICK_BASE_URL='https://api.dida365.com/open/v1'
   TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize'
   TICKTICK_TOKEN_URL='https://dida365.com/oauth/token'
   

3. TickTick と同じ認証手順に従います

Claude for Desktop での使用

1. Claude for Desktop をインストールします

2. Claude for Desktop の設定ファイルを編集します：

   macOS：

   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows：

   notepad %APPDATA%\Claude\claude_desktop_config.json
   

3. 絶対パスを使用して、TickTick MCP サーバーの設定を追加します：

   {
      "mcpServers": {
         "ticktick": {
            "command": "<absolute path to uv>",
            "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
         }
      }
   }
   

4. Claude for Desktop を再起動します

接続すると、Claude で利用可能な TickTick MCP サーバーのツールが、🔨（ツール）アイコンで示されます。

利用可能な MCP ツール

ツール	説明	パラメーター
get_projects	TickTick のすべてのプロジェクトを一覧表示します	なし
get_project	特定のプロジェクトの詳細を取得します	project_id
get_project_tasks	プロジェクト内のすべてのタスクを一覧表示します	project_id
get_task	特定のタスクの詳細を取得します	project_id、task_id
create_task	新しいタスクを作成します	title、project_id、content（任意）、start_date（任意）、due_date（任意）、priority（任意）
update_task	既存のタスクを更新します	task_id、project_id、title（任意）、content（任意）、start_date（任意）、due_date（任意）、priority（任意）
complete_task	タスクを完了済みにします	project_id、task_id
delete_task	タスクを削除します	project_id、task_id
create_project	新しいプロジェクトを作成します	name、color（任意）、view_mode（任意）
delete_project	プロジェクトを削除します	project_id

タスク専用 MCP ツール

タスクの取得と検索

ツール	説明	パラメーター
get_all_tasks	すべてのプロジェクトから全タスクを取得します	なし
get_tasks_by_priority	優先度で絞り込んだタスクを取得します	priority_id（0：なし、1：低、3：中、5：高）
search_tasks	タイトル、内容、サブタスクからタスクを検索します	search_term

日付に基づくタスクの取得

ツール	説明	パラメーター
get_tasks_due_today	今日が期限のタスクをすべて取得します	なし
get_tasks_due_tomorrow	明日が期限のタスクをすべて取得します	なし
get_tasks_due_in_days	X 日後が期限のタスクを取得します	days（0 = 今日、1 = 明日など）
get_tasks_due_this_week	今後 7 日以内が期限のタスクを取得します	なし
get_overdue_tasks	期限を過ぎたタスクをすべて取得します	なし

Getting Things Done（GTD）フレームワーク

ツール	説明	パラメーター
get_engaged_tasks	「取り組み中」のタスク（優先度が高い、または期限超過）を取得します	なし
get_next_tasks	「次の」タスク（優先度が中、または明日が期限）を取得します	なし
batch_create_tasks	複数のタスクを一度に作成します	tasks（タスク辞書のリスト）

Claude 向けプロンプトの例

TickTick MCP サーバーに接続した後、Claude で使用できるプロンプトの例を紹介します。

一般

• 「TickTick のすべてのプロジェクトを表示して」
• 「仕事のプロジェクトに、優先度を高にして『MCP サーバーのドキュメントを完成させる』という新しいタスクを作成して」
• 「個人用プロジェクトのすべてのタスクを一覧表示して」
• 「『食料品を買う』タスクを完了済みにして」
• 「青色の『休暇の計画』という新しいプロジェクトを作成して」
• 「TickTick で次の締め切りはいつ？」

タスクの絞り込みに関する質問

• 「今日が期限のタスクは何？」
• 「期限を過ぎている項目をすべて表示して」
• 「今週が期限のタスクをすべて表示して」
• 「『project alpha』に関するタスクを検索して」
• 「タイトルまたは説明に『client』が含まれるタスクをすべて表示して」
• 「優先度が高いタスクをすべて表示して」

GTD ワークフロー

David Allen の「Getting Things Done」フレームワークに従って、「Engaged」と「Next」のアクションを管理します。

• Engaged では、優先度が高い、今日が期限、または期限を過ぎたタスクを取得します。
• Next では、優先度が中、または明日が期限のタスクを取得します。
• 複雑なアクションは、batch_create_tasks を使って小さなアクションに分割します。

例：

• 「Engaged リストの項目を使って、午後 2 時から 8 時までの残りの時間をタイムブロックして」
• 「次のアクションを順番に確認して、明日何に集中すべきか一緒に考えて」
• 「このプロジェクトを、実行可能な 5 つの小さなタスクに分割して」

開発

プロジェクト構成

ticktick-mcp/
├── .env.template          # Template for environment variables
├── README.md              # Project documentation
├── requirements.txt       # Project dependencies
├── setup.py               # Package setup file
├── test_server.py         # Test script for server configuration
└── ticktick_mcp/          # Main package
    ├── __init__.py        # Package initialization
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py             # Command-line interface
    └── src/               # Source code
        ├── __init__.py    # Module initialization
        ├── auth.py        # OAuth authentication implementation
        ├── server.py      # MCP server implementation
        └── ticktick_client.py  # TickTick API client

認証フロー

このプロジェクトでは、TickTick 用の OAuth 2.0 フローを完全に実装しています。

1. 初期設定：ユーザーが TickTick API のクライアント ID とシークレットを入力します
2. ブラウザー認証：ユーザーはアクセスを許可するため、TickTick にリダイレクトされます
3. トークンの受信：ローカルサーバーが認証コードを含む OAuth コールバックを受信します
4. トークンの交換：認証コードをアクセストークンとリフレッシュトークンに交換します
5. トークンの保存：トークンはローカルの .env ファイルに安全に保存されます
6. トークンの更新：アクセストークンの有効期限が切れると、クライアントが自動的に更新します

OAuth フロー全体をプログラムで処理することで、ユーザーエクスペリエンスをシンプルにします。

コントリビューション

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

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

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