TickTick MCP サーバー

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

✨ 特徴

このサーバーは、次のように分類される MCP ツールを介して TickTick 機能への包括的なアクセスを提供します。

タスク管理: タスクの作成、更新 (TickTick の日付形式への変換を含む)、削除、完了、移動。
**サブタスク管理:**既存のタスクをリンクしてサブタスクを作成します。
タスクの取得:
- 未完了のタスクをすべて取得します。
- ID または特定のフィールドでタスクを取得します。
- 日付範囲内で完了したタスクを取得します。
- 特定のプロジェクトからタスクを取得します。
- さまざまな基準 (優先度、プロジェクト、タグなど) に基づいてタスクをフィルタリングします。
**プロジェクト/タグ管理:**すべてのプロジェクト、タグ、プロジェクトフォルダーを取得します。
**ヘルパーツール:**日時文字列を必要な TickTick 形式に変換します。

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

🚀 はじめに

このサーバーは、非公式のticktick-pyライブラリを使用して TickTick API と対話します。

前提条件

Python >= 3.10
TickTick および API 資格情報へのアクセス (下記参照)。

設定

**TickTickアプリケーションの登録：**サーバーを使用する前に、TickTickにアプリケーションを登録してAPI認証情報を取得する必要があります。ticktick ticktick-pyドキュメントに基づいて、以下の手順に従ってください。
- TickTick OpenAPI ドキュメントにアクセスし、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 が環境変数に保存されていることを確認してください。
**環境変数：**サーバーは、先ほど取得した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)

**認証 (初回実行):**初回実行時 (直接または MCP クライアント経由)、基盤となるticktick-pyライブラリが OAuth2 認証フローを開始します。
- Web ブラウザウィンドウが自動的に開くか、コンソール/ログ出力に URL が印刷されます。
- この URL にアクセスし、必要に応じて TickTick にログインし、アプリケーションを承認する必要があります (読み取りおよび書き込み権限を付与します)。
- 承認後、指定したTICKTICK_REDIRECT_URIにリダイレクトされます。
  - コンソールでは**、リダイレクトされた完全な URL** ( code=パラメータを含む) をターミナルに貼り付けるように求められます。
- 検証が成功すると、 .envファイルと同じディレクトリに.token-oauthファイルが作成されます。
- このファイルは認証トークンをキャッシュするため、通常はこの手動認証手順を約 6 か月ごとに 1 回、またはトークンが無効になった場合にのみ実行する必要があります。

サーバーの実行

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

1. MCP クライアント経由 (AI アシスタント統合に推奨):

MCPクライアント（Claude Desktop、VS Code Agent Modeなど）をサーバーに接続できるように設定します。設定例：

{
 "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 タスク管理サービスと対話するための次のツールを提供します。

タスク管理

ticktick_create_task
- TickTickで新しいタスクを作成します
- 入力:
  - title (文字列): タスクのタイトル。必須。
  - projectId (文字列、オプション): タスクを追加するプロジェクトの ID。
  - content (文字列、オプション): タスクの追加の詳細またはメモ。
  - desc (文字列、オプション): タスクの説明。
  - allDay (ブール値、オプション): タスクが 1 日中にわたる場合は True に設定します。
  - startDate (文字列、オプション): ISO 8601 形式の開始日時。
  - dueDate (文字列、オプション): ISO 8601 形式の期日/時刻。
  - timeZone (文字列、オプション): IANA タイムゾーン名 (例: 'Asia/Seoul')。
  - reminders (文字列の配列、オプション): RFC 5545 形式のリマインダートリガーのリスト。
  - repeat (文字列、オプション): RFC 5545 形式の繰り返しルール。
  - priority （整数、オプション）：タスクの優先度（0=なし、1=低、3=中、5=高）。
  - sortOrder (整数、オプション): カスタムの並べ替え順序の値。
  - items (オブジェクトの配列、オプション): サブタスク辞書のリスト。
ticktick_update_task
- 既存のタスクを更新します
- 入力:
  - task_object (オブジェクト): タスクidを含む、更新するタスクプロパティを含む辞書。
ticktick_delete_tasks
- 1つ以上のタスクを削除します
- 入力:
  - task_ids (文字列または文字列の配列): 削除する単一のタスク ID またはタスク ID のリスト。
ticktick_complete_task
- タスクを完了としてマークします
- 入力:
  - task_id (文字列): 完了としてマークするタスクの ID。
ticktick_move_task
- タスクを別のプロジェクトに移動する
- 入力:
  - task_id (文字列): 移動するタスクの ID。
  - new_project_id (文字列): 宛先プロジェクトの ID。
ticktick_make_subtask
- あるタスクを別のタスクのサブタスクにする
- 入力:
  - parent_task_id (文字列): 親となるタスクの ID。
  - child_task_id (文字列): サブタスクとなるタスクの ID。

タスクの取得

ticktick_get_by_id
- IDで特定のオブジェクト（タスク、プロジェクトなど）を取得します
- 入力:
  - obj_id (文字列): 取得するオブジェクトの一意の ID。
ticktick_get_all
- 指定されたタイプのすべてのオブジェクトを取得します
- 入力:
  - search (文字列): 取得するオブジェクトのタイプ (例: 'tasks'、'projects'、'tags')。
ticktick_get_tasks_from_project
- 特定のプロジェクトから未完了のタスクをすべて取得します
- 入力:
  - project_id (文字列): プロジェクトの ID。
ticktick_filter_tasks

さまざまな基準に基づいてタスクをフィルタリングします
入力:
- filter_criteria (オブジェクト): 次のようなフィルタリングパラメータを持つ辞書:
  - status (文字列): タスクのステータス ('uncompleted' または 'completed')。
  - project_id (文字列、オプション): タスクをフィルタリングするプロジェクト ID。
  - tag_label (文字列、オプション): タスクをフィルタリングするタグ名。
  - priority （整数、オプション）：優先度。
  - due_start_date (文字列、オプション): 期日フィルターの ISO 形式の開始日。
  - due_end_date (文字列、オプション): 期日フィルターの ISO 形式の終了日。
  - completion_start_date (文字列、オプション): 完了日フィルターの開始日。
  - completion_end_date (文字列、オプション): 完了日フィルターの終了日。
  - sort_by_priority (ブール値、オプション): 結果を優先度で並べ替えます。
  - tz (文字列、オプション): 日付を解釈するためのタイムゾーン。

ヘルパーツール

ticktick_convert_datetime_to_ticktick_format

ISO 8601 の日付/時刻文字列を TickTick API 形式に変換します
入力:
- datetime_iso_string (文字列): ISO 8601 形式の日付/時刻文字列。
- tz (文字列): 日付/時刻を解釈するための 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.

🤝 貢献する

貢献を歓迎します！お気軽に問題を報告したり、プルリクエストを送信してください。

📜 ライセンス

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

🔗 参照

モデルコンテキストプロトコルサーバー: さまざまなツールおよびプラットフォーム用の MCP サーバーのリファレンス実装の中央リポジトリ。
modelcontextprotocol.io : モデルコンテキストプロトコルの公式ドキュメント。
pietrozullo/mcp-use : MCP サーバーと対話するクライアント/エージェントを構築するための人気の Python ライブラリ。
lazeroffmichael/ticktick-py : このプロジェクトで認証と API のやり取りを処理するために使用する非公式の TickTick API ライブラリ。

TickTick MCP Server

Integrations