TickTick MCP Server

TickTick MCP Server

タスク管理、プロジェクト整理、習慣の追跡などを実現する、TickTick API 用の MCP サーバーです。

機能

• ✅ タスク管理：利用可能なすべてのプロパティを使用して、タスクの作成、読み取り、更新、削除ができます
• 📊 プロジェクト管理：カスタマイズ可能なビューを使用して、プロジェクトの作成、読み取り、更新、削除ができます
• 📋 サブタスクのサポート：親タスク内のサブタスクを完全に管理できます
• 🔄 タスクの完全な制御：優先度、期限、リマインダー、繰り返しルールを設定できます
• 🔐 OAuth 認証：安全な API アクセスのための OAuth2 を完全に実装しています
• ⚠️ 包括的なエラー処理：一般的な問題に対して明確なエラーメッセージを表示します

ツール

1. get_task_by_ids

   • プロジェクト ID とタスク ID を指定して、特定のタスクを取得します
   • 入力：
     • projectId (string)：プロジェクト識別子
     • taskId (string)：タスク識別子
   • 戻り値：TickTickTaskSchema に一致するタスクオブジェクト

2. create_task

   • プロジェクトに新しいタスクを作成します
   • 入力：
     • title (string)：タスク名
     • projectId (string)：プロジェクト ID
     • content (optional string)：タスクの内容
     • desc (optional string)：タスクの説明
     • isAllDay (optional boolean)：終日タスクかどうか
     • startDate (optional string)："yyyy-MM-dd'T'HH:mm:ssZ" 形式のタスク開始日
     • dueDate (optional string)："yyyy-MM-dd'T'HH:mm:ssZ" 形式のタスク期限
     • timeZone (optional string)：タスクのタイムゾーン（例："America/Los_Angeles"）
     • reminders (optional string[])：iCalendar 形式のリマインダートリガーのリスト
     • repeatFlag (optional string)：iCalendar 形式のタスク繰り返しフラグ
     • priority (optional number)：タスクの優先度（なし：0、低：1、中：3、高：5）
     • sortOrder (optional string)：タスクの並べ替え順
     • items (optional array)：以下を含むサブタスクのリスト：
       • title (string)：サブタスク項目名
       • startDate (optional string)："yyyy-MM-dd'T'HH:mm:ssZ" 形式のサブタスクの日付
       • isAllDay (optional boolean)：サブタスク項目が終日かどうか
       • sortOrder (optional number)：サブタスク項目の並べ替え順
       • timeZone (optional string)：サブタスクのタイムゾーン
       • status (optional number)：完了ステータス（通常：0、完了：1）
       • completedTime (optional string)："yyyy-MM-dd'T'HH:mm:ssZ" 形式の完了時刻
   • 戻り値：作成された、TickTickTaskSchema に一致するタスクオブジェクト

3. update_task

   • 既存のタスクを更新します
   • 入力：
     • taskId (string)：タスク識別子 - パス
     • id (string)：タスク識別子 - ボディ
     • projectId (string)：プロジェクト ID
     • create_task のすべての任意フィールド
   • 戻り値：更新された、TickTickTaskSchema に一致するタスクオブジェクト

4. complete_task

   • タスクを完了としてマークします
   • 入力：
     • taskId (string)：タスク識別子
     • projectId (string)：プロジェクト識別子
   • 戻り値：なし

5. delete_task

   • プロジェクトからタスクを削除します
   • 入力：
     • taskId (string)：タスク識別子
     • projectId (string)：プロジェクト識別子
   • 戻り値：なし

6. get_user_projects

   • 認証済みユーザーのすべてのプロジェクトを取得します
   • 入力：なし
   • 戻り値：TickTickProjectSchema に一致するプロジェクトオブジェクトの配列

7. get_project_by_id

   • ID を指定して、特定のプロジェクトを取得します
   • 入力：
     • projectId (string)：プロジェクト識別子
   • 戻り値：TickTickProjectSchema に一致するプロジェクトオブジェクト

8. get_project_with_data

   • タスクと列を含むプロジェクトの詳細を取得します
   • 入力：
     • projectId (string)：プロジェクト識別子
   • 戻り値：以下を含むオブジェクト：
     • project：TickTickProjectSchema に一致するプロジェクトオブジェクト
     • tasks：TickTickTaskSchema に一致するタスクオブジェクトの配列
     • columns：列オブジェクトの任意の配列。以下を含みます：
       • id (optional string)
       • projectId (optional string)
       • name (optional string)
       • sortOrder (optional number)

9. create_project

   • 新しいプロジェクトを作成します
   • 入力：
     • name（string）：プロジェクト名
     • color（任意の string）：プロジェクトの色（デフォルト：'#4772FA'）
     • viewMode（任意の string）：表示モード（'list'、'kanban'、'timeline'）（デフォルト：'list'）
     • kind（任意の string）：プロジェクトの種類（'TASK'、'NOTE'）（デフォルト：'TASK'）
   • 戻り値：TickTickProjectSchema に一致する作成済みプロジェクトオブジェクト

10. update_project

    • 既存のプロジェクトを更新します
    • 入力：
      • projectId（string）：プロジェクト識別子
      • name（任意の string）：プロジェクト名
      • color（任意の string）：プロジェクトの色
      • sortOrder（任意の number）：プロジェクトの並べ替え順
      • viewMode（任意の string）：表示モード（'list'、'kanban'、'timeline'）
      • kind（任意の string）：プロジェクトの種類（'TASK'、'NOTE'）
    • 戻り値：TickTickProjectSchema に一致する更新済みプロジェクトオブジェクト

11. delete_project

    • プロジェクトを削除します
    • 入力：
      • projectId（string）：プロジェクト識別子
    • 戻り値：void

スキーマの参照

• TickTickTaskSchema：以下を含むタスクオブジェクトの構造を定義します。

  • タスクの基本プロパティ（id、title、description）
  • 日付と時刻の設定
  • 優先度とステータス
  • チェックリスト項目とサブタスク

• TickTickProjectSchema：以下を含むプロジェクトオブジェクトの構造を定義します。

  • プロジェクトの識別情報と名前
  • 表示設定（色、表示モード）
  • 権限と組織

タスクのプロパティ

タスクを作成または更新する際、次のプロパティを指定できます。

• 優先度レベル：
  • 0：なし
  • 1：低
  • 3：中
  • 5：高
• ステータス値：
  • 0：通常（未完了）
  • 2：完了
• リマインダー形式：
  • 例：["TRIGGER:P0DT9H0M0S", "TRIGGER:PT0S"]
  • iCalendar の TRIGGER 形式に従います
• 繰り返しルール（repeatFlag）：
  • 例："RRULE:FREQ=DAILY;INTERVAL=1"
  • RFC 5545 の繰り返しルールを使用します
• 日付形式：
  • ISO 8601 形式："yyyy-MM-dd'T'HH:mm:ssZ"
  • 例："2019-11-13T03:00:00+0000"

プロジェクトのプロパティ

プロジェクトを作成または更新する際、次のプロパティを使用できます。

• 表示モード：
  • "list"：標準のリスト表示
  • "kanban"：カンバンボード表示
  • "timeline"：タイムライン表示
• プロジェクトの種類：
  • "TASK"：タスク指向のプロジェクト
  • "NOTE"：メモ指向のプロジェクト

セットアップ

OAuth 認証

TickTick で OAuth 認証を有効にするには、アプリを登録して API 認証情報を取得する必要があります。

• TickTick Developer Portal でアカウントを作成します
• 新しいアプリケーションを登録します
• OAuth リダイレクト URL を http://localhost:8000/callback に設定します
• 生成された Client ID（TICKTICK_CLIENT_ID）と Client Secret（TICKTICK_CLIENT_SECRET）をコピーします

初回認証フロー

TickTick MCP サーバーを初めて使用する際：

1. アプリケーションの認証を求められます
2. TickTick のログインページがブラウザーウィンドウで開きます
3. ログイン後、権限の付与を求められます
4. アクセストークンがページに表示されます
5. このトークンをコピーし、TICKTICK_ACCESS_TOKEN 環境変数に設定します

アクセストークンの生成

初回セットアップ時やトークンの有効期限が切れたときに新しいアクセストークンを生成するには、以下の手順に従ってください。

1. 次のいずれかの方法で認証情報を設定します。

   オプション 1：.env ファイル（推奨）

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

   TICKTICK_CLIENT_ID="<YOUR_CLIENT_ID>"
   TICKTICK_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
   

   次に、ファイルを読み込みます。

   source .env
   

   この方法が推奨される理由は次のとおりです。

   • ターミナルのセッション間で認証情報が保持されます
   • 複数の設定をより簡単に管理できます
   • シェルの履歴から漏えいするリスクが低くなります
   • 簡単にバックアップできます（バージョン管理の対象から除外することを忘れないでください）

   オプション 2：ターミナルの環境変数

   認証情報に特殊文字が含まれる場合は、シングルクォートを使用してください。これらの変数は現在のターミナルセッションでのみ保持されます。

   export TICKTICK_CLIENT_ID='<YOUR_CLIENT_ID>'
   export TICKTICK_CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
   

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

   公開済みパッケージを使用する場合：

   npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth
   

   MCP サーバーをローカルで実行する場合：

   npm run start:auth
   

   処理は次のとおり進みます。

   • 既定のブラウザーを起動します
   • TickTick のログインページに移動します
   • 必要な権限を要求します
   • アクセストークンを生成して表示します

3. アクセストークンを保存します。

   echo "TICKTICK_ACCESS_TOKEN=\"<GENERATED_TOKEN>\"" >> .env
   source .env
   

セキュリティに関するヒント：

• .env を .gitignore ファイルに追加してください
• 認証情報をバージョン管理にコミットしないでください
• アクセストークンの有効期限は 180 日です。期限が切れたら再生成する必要があります

Claude Desktop での使用

Claude Desktop で使用するには、claude_desktop_config.json に次の内容を追加します。

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo.ai/mcp-server-ticktick"],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "ticktick": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TICKTICK_CLIENT_ID",
        "-e",
        "TICKTICK_CLIENT_SECRET",
        "-e",
        "TICKTICK_ACCESS_TOKEN",
        "mcp/ticktick"
      ],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Smithery を使用したインストール

Smithery 経由で Claude Desktop 用の ticktick-mcp-server を自動的にインストールするには：

npx -y @smithery/cli install @alexarevalo9/ticktick-mcp-server --client claude

ビルド

Docker のビルド：

docker build -t mcp/ticktick -f src/ticktick/Dockerfile .

ライセンス

この MCP サーバーは MIT ライセンスのもとでライセンスされています。MIT ライセンスの利用規約に従うことを条件として、ソフトウェアを自由に使用、変更、配布できます。詳しくは、プロジェクトリポジトリの LICENSE ファイルをご覧ください。