Ticktick Mcp

TickTick MCP サーバー

この MCP サーバーで、TickTick のワークフローを強化できます。ticktick-py ライブラリを基盤として構築されており、フィルタリング機能が大幅に向上しています。これにより、AI アシスタントや MCP 互換アプリケーション（Claude Desktop、VS Code Agent Mode、mcp-use など）が、タスクをより正確かつ強力に操作できます。

✨ 機能

このサーバーでは、以下のカテゴリに分類された MCP ツールを通じて、TickTick の機能を包括的に利用できます。

• タスク管理： タスクの作成、更新（TickTick の日付形式への変換を含む）、削除、完了、移動を行えます。
• サブタスク管理： 既存のタスクを紐付けてサブタスクを作成できます。
• タスクの取得：
  • 未完了のタスクをすべて取得します。
  • ID または特定のフィールドを指定してタスクを取得します。
  • 期間を指定して完了済みタスクを取得します。
  • 特定のプロジェクトからタスクを取得します。
  • 優先度、プロジェクト、タグなど、さまざまな条件に基づいてタスクをフィルタリングします。
• プロジェクト／タグ管理： すべてのプロジェクト、タグ、プロジェクトフォルダーを取得します。
• ヘルパーツール： 日時文字列を、TickTick で必要な形式に変換します。

詳細な仕様については、src/ticktick_mcp/tools/ ディレクトリ内のツール定義を参照してください。

🚀 はじめに

このサーバーは、非公式の ticktick-py library を利用して TickTick API と連携します。

前提条件

• Python >= 3.10
• TickTick と API 認証情報へのアクセス（下記を参照）。

セットアップ

1. TickTick アプリケーションを登録する： サーバーを使用する前に、API 認証情報を取得するため、TickTick にアプリケーションを登録する必要があります。ticktick-py のドキュメントに沿って、次の手順を実行してください。

   • TickTick OpenAPI Documentation にアクセスし、TickTick アカウントでログインします。
   • 右上の Manage Apps をクリックします。
   • +App Name ボタンをクリックして新しいアプリを登録します。アプリケーション名（例：「MCP Server」）を入力します。
   • 作成したら、アプリの詳細を編集します。生成された Client ID と Client Secret を控えておきます。
   • OAuth Redirect URL には、アプリケーションの認証後にリダイレクトする URL を入力します。有効な URL である必要はありません。
     • ローカル開発では、http://localhost:8080/redirect または http://127.0.0.1:8080/ がよく使われます。
     • この URL と完全に一致する値を環境変数に保存してください。

2. 環境変数： サーバーには、取得した TickTick API 認証情報に加えて、TickTick のログイン情報も必要です。デフォルトでは、~/.config/ticktick-mcp/.env にある .env ファイルを探します。

   • ディレクトリが存在しない場合、サーバーが ~/.config/ticktick-mcp/ ディレクトリを作成することもありますが、手動で作成するほうが確実です。
   • このディレクトリ内に .env ファイルを手動で作成する必要があります。
   • または、Python からサーバーを直接実行する場合に限り、--dotenv-dir コマンドライン引数で別のディレクトリを指定できます（下記の「サーバーの実行」を参照）。

   .env ファイルには次の内容を記述してください。

TICKTICK_CLIENT_ID=your_client_id   # Obtained in Step 1
TICKTICK_CLIENT_SECRET=your_client_secret # Obtained in Step 1
TICKTICK_REDIRECT_URI=your_redirect_uri # Entered in Step 1 (must match exactly)
TICKTICK_USERNAME=your_ticktick_email # Your TickTick login email
TICKTICK_PASSWORD=your_ticktick_password # Your TickTick login password (or app password if enabled)

3. 認証（初回実行時）： 初回実行時（直接実行する場合でも、MCP クライアント経由の場合でも）、内部で使用される ticktick-py ライブラリが OAuth2 認証フローを開始します。
   • ウィンドウが自動的に開くか、URL がコンソールまたはログ出力に表示されます。
   • この URL にアクセスし、必要に応じて TickTick にログインして、アプリケーションを認証（読み取りと書き込みの権限を付与）します。
   • 認証後、指定した TICKTICK_REDIRECT_URI にリダイレクトされます。
     • コンソールの指示に従って、リダイレクト先の完全な URL（code= パラメーターを含む）をターミナルに貼り付けてください。
   • 検証に成功すると、.env ファイルと同じディレクトリに .token-oauth ファイルが作成されます。
   • このファイルには認証トークンがキャッシュされるため、通常はこの手動認証を行うのは約 6 か月に 1 回、またはトークンが無効になったときだけです。

サーバーの実行

サーバーは主に次の 2 つの方法で実行できます。

1. MCP クライアント経由（AI アシスタントとの連携に推奨）：

Claude Desktop、VS Code Agent Mode などの MCP クライアントで、このサーバーを使用するように設定します。設定例：

{
 "mcpServers": {
 "ticktick": {
  "command": "uvx",
  "args": [
  "--from",
  "git+https://github.com/jen6/ticktick-mcp.git",
  "ticktick-mcp"
  // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
  // but standard clients might not support passing extra args easily.
  ]
 }
 }
}

🔧 ツール

このサーバーには、TickTick のタスク管理サービスを操作するための次のツールが用意されています。

タスク管理

1. ticktick_create_task

   • TickTick に新しいタスクを作成します
   • 入力：
     • title (string)：タスクのタイトルです。必須です。
     • projectId (string, optional)：タスクを追加するプロジェクトの ID です。
     • content (string, optional)：タスクの追加情報やメモです。
     • desc (string, optional)：タスクの説明です。
     • allDay (boolean, optional)：タスクが終日続く場合は True に設定します。
     • startDate (string, optional)：ISO 8601 形式の開始日時です。
     • dueDate (string, optional)：ISO 8601 形式の期限日時です。
     • timeZone (string, optional)：IANA タイムゾーン名です（例：'Asia/Seoul'）。
     • reminders (array of strings, optional)：RFC 5545 形式のリマインダートリガーの一覧です。
     • repeat (string, optional)：RFC 5545 形式の繰り返しルールです。
     • priority (integer, optional)：タスクの優先度です（0=なし、1=低、3=中、5=高）。
     • sortOrder (integer, optional)：カスタムの並べ替え順序の値です。
     • items (array of objects, optional)：サブタスクの辞書の一覧です。

2. ticktick_update_task

   • 既存のタスクを更新します
   • 入力：
     • task_object (object)：タスクの id を含む、更新するタスクのプロパティを指定した辞書です。

3. ticktick_delete_tasks

   • 1 つ以上のタスクを削除します
   • 入力：
     • task_ids (string or array of strings)：削除する単一のタスク ID、またはタスク ID の一覧です。

4. ticktick_complete_task

   • タスクを完了としてマークします
   • 入力：
     • task_id (string)：完了としてマークするタスクの ID です。

5. ticktick_move_task

   • タスクを別のプロジェクトに移動します
   • 入力：
     • task_id (string)：移動するタスクの ID です。
     • new_project_id (string)：移動先プロジェクトの ID です。

6. ticktick_make_subtask

   • あるタスクを別のタスクのサブタスクにします
   • 入力：
     • parent_task_id (string)：親タスクになるタスクの ID です。
     • child_task_id (string)：サブタスクになるタスクの ID です。

タスクの取得

7. ticktick_get_by_id

   • ID を指定して特定のオブジェクト（タスク、プロジェクトなど）を取得します
   • 入力：
     • obj_id (string)：取得するオブジェクトの一意の ID です。

8. ticktick_get_all

   • 指定した種類のオブジェクトをすべて取得します
   • 入力：
     • search (string)：取得するオブジェクトの種類です（例：'tasks'、'projects'、'tags'）。

9. ticktick_get_tasks_from_project

   • 特定のプロジェクトから未完了のタスクをすべて取得します
   • 入力：
     • project_id (string)：プロジェクトの ID です。

10. ticktick_filter_tasks

    • さまざまな条件に基づいてタスクを絞り込みます
    • 入力：
      • filter_criteria (object)：次のような絞り込みパラメーターを指定した辞書です。
        • status (string)：タスクのステータス（'uncompleted' または 'completed'）です。
        • project_id (string, optional)：タスクの絞り込みに使用するプロジェクト ID です。
        • tag_label (string, optional)：タスクの絞り込みに使用するタグ名です。
        • priority (integer, optional)：優先度です。
        • due_start_date (string, optional)：期限による絞り込みの開始日（ISO 形式）です。
        • due_end_date (string, optional)：期限による絞り込みの終了日（ISO 形式）です。
        • completion_start_date (string, optional)：完了日による絞り込みの開始日です。
        • completion_end_date (string, optional)：完了日による絞り込みの終了日です。
        • sort_by_priority (boolean, optional)：優先度順に結果を並べ替えます。
        • tz (string, optional)：日付の解釈に使用するタイムゾーンです。

ヘルパーツール

11. ticktick_convert_datetime_to_ticktick_format
    • ISO 8601 形式の日付／日時文字列を TickTick API 形式に変換します
    • 入力：
      • datetime_iso_string (string)：ISO 8601 形式の日付／日時文字列です。
      • tz (string)：日付／日時の解釈に使用する IANA タイムゾーン名です。

🤖 エージェントプロンプトのサンプル

## Persona: Daily Stand-up Agent

- **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
- **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks

---

## Core Features & Workflow

1. **Fetch Current Time** 
 - Retrieve current time using `time mcp`.

2. **Session Start & Data Loading** 
 - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
 - Call TickTick MCP API to fetch all tasks due **today**. 
 - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").

3. **Daily Briefing**
 Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:

 **Tasks Due Today:**
 - Task Name 1
 - Task Name 2
 …

 **Overdue Tasks:**
 - Task Name 3
 - Task Name 4
 …

4. **Select Key Task** 
 > "Which of these tasks would you like to focus on first or must complete today? 
 > Or is there another important task you'd like to add?"

5. **Task Breakdown (Subtask Creation)** 
 - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
 - Example (if "Write project report" is selected):
  1. Draft outline & table of contents (10 min) 
  2. Gather & analyze data (30 min) 
  3. Write section drafts (1 h) 
  4. Review & revise draft (30 min) 
  5. Final submission (10 min)

6. **Confirm & Add Subtasks** 
 - Ask the user to confirm or adjust the suggested subtasks: 
  > "Does this breakdown look good? Any changes?" 
 - Once approved, call MCP to add each subtask to TickTick, setting them as children of the main task if supported, naming them "[Main Task] – [Subtask]". 
 mcp.ticktick.addTask({
  name: "[Main Task] – [Subtask]",
  parentId: "..."
 });

7. **Session Close** 
 > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"

---

## Additional Guidelines

- **Tone & Manner**: Friendly, proactive, and organized. 
- **MCP Interface Examples**: 
 // Fetch today's due tasks
 mcp.ticktick.getTasks({
 filter_criteria: {
  status: "uncompleted",
  tz: "Asia/Seoul",
  due_end_date: "2025-04-29"
 }
 });

 // Add a subtask
 mcp.ticktick.addTask({
 name: "Project Report – Write Draft",
 parentId: "task123"
 });
- **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
- **Clarity**: Present task lists and subtask suggestions clearly. 
- **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.

🤝 コントリビューション

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

📜 ライセンス

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

🔗 関連情報

• Model Context Protocol Servers：さまざまなツールやプラットフォーム向けの MCP サーバーのリファレンス実装を集めた中央リポジトリです。
• modelcontextprotocol.io：Model Context Protocol の公式ドキュメントです。
• pietrozullo/mcp-use：MCP サーバーと連携するクライアント／エージェントを構築するための、人気の Python ライブラリです。
• lazeroffmichael/ticktick-py：このプロジェクトで認証と API 連携に使用している、非公式の TickTick API ライブラリです。