Ticktick-MCP-Enhanced

滴答清单 MCP サーバー

英語版はこちら！

これは、滴答清单の公式 API をベースにしたローカル MCP サービスです。ユーザーは LLM とエージェントアプリを通じて、簡単にタスクを管理できます。

🔗 API ドキュメント：滴答清单公式 OpenAPI

---

📢 更新情報

• 2026-07-04 タスクの移動、完了済みタスクの取得、プロジェクトの更新、習慣管理モジュールを追加 — 合計 9 個の新しいツール（move_tasks、get_completed_tasks、update_projects、および習慣モジュールの get_all_habits、get_habit、create_habits、update_habits、checkin_habits、get_habit_checkins）。
• 2026-07-02 認証システムを再構築 — 環境変数による設定を廃止し、実行時に login ツールへ OAuth 認証情報を直接渡す方式に変更。中国版／国際版のワンクリック切り替えに対応。
• 2026-05-12 ツールの説明を抽出 — すべてのツールのプロンプトを個別の .txt ファイルに抽出し、メンテナンスや変更を容易にしました。
• 2026-05-09 リマインダーのパラメーターを追加 — タスクの作成時と更新時に reminders に対応し、期限前のプッシュ通知リマインダーを設定できます。
• 2026-01-29 プロジェクト構成を再構築 — src ディレクトリレイアウトに移行し、コードをより適切に整理しました。
• 2026-01-17 ログシステムをアップグレード — セッションベースのファイル専用ログに変更し、操作の追跡をより明確にしました。
• 2026-01-12 全面的に再構築 — シームレスなローカル OAuth コールバック認証と統一されたログ追跡を実装し、python-dotenv への依存を廃止しました。
• 2025-12-07 タイムゾーン処理の問題を修正しました。
• 2025-10-17 優先度パラメーターの自然言語マッピングと認証フローを最適化しました。

✨ 機能

• 🤖 AI エージェントでタスクを管理：自然言語の指示でタスクの作成、検索、更新、完了ができます。
• 🔑 実行時の OAuth 認証：login ツールに認証情報を直接渡すと、ブラウザーで認証ページが自動的に開きます。環境変数の設定は不要です。
• 📅 タスク管理：タスク、プロジェクト、サブタスクの作成と、複雑な検索機能に対応します。
• 🔍 高度な検索：日付範囲、優先度、キーワードなど、複数の条件でタスクを絞り込めます。

🚀 インストールと使用方法

前提条件

• Python バージョン：3.10 以降
• LLM クライアント（Claude Desktop、OpenCode など）

インストール手順

# 克隆项目
git clone https://github.com/Code-MonkeyZhang/ticktick-mcp-enhanced.git
cd ticktick-mcp-enhanced

# 创建虚拟环境并安装
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

uv pip install -e .

LLM クライアントの設定

Claude Desktop またはその他の LLM アプリの設定ファイルに、次の内容を追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": ["/path/to/ticktick-mcp-enhanced/.venv/bin/ticktick-mcp"],
      "enabled": true
    }
  }
}

注意：/path/to/ticktick-mcp-enhanced をプロジェクトの実際の絶対パスに置き換えてください。Windows ユーザーは、二重のバックスラッシュ \\ またはスラッシュ / を使用してください。

🔑 API 認証情報の取得

滴答清单開発者センター（中国国内のアカウント）または TickTick Developer Center（国外のアカウント）でアプリを登録します。

1. "New App" をクリックします。
2. Redirect URI に http://localhost:8000/callback を設定します。
3. Client ID と Client Secret を保存します。

使用方法

1. LLM クライアントを再起動します
2. 滴答清单にログインします
   • 会話に「滴答清单にログインして」と入力し、Client ID と Client Secret を入力します。
   • AI が login ツールを呼び出し、ブラウザーで滴答清单の認証ページが自動的に開きます。
   • ブラウザーで許可をクリックして、認証を完了します。
   • ログイン状態はローカルに保存されるため、以降は再ログインする必要はありません。
3. 使用を開始します
   • タスクを確認：「今日のタスクを確認して」
   • タスクを作成：「タスクを作成して：明日の午後3時に会議」
   • プロジェクトを検索：「すべてのリストを確認して」

🧰 可用工具

此 MCP 向你的 LLM 客户端公开以下工具。

类别	工具名称	功能描述
认证	ticktick_status	检查当前的连接和授权状态。
	login	传入 OAuth 凭据，启动浏览器授权流程并完成登录。
清单	get_all_projects	获取所有清单列表。
	get_project_info	查看特定清单及其中的任务。
	create_project	创建一个新的项目。
	update_projects	原地修改项目名称、颜色、视图或类型（支持批量）。
	delete_projects	删除项目。
任务	create_tasks	创建任务（支持智能时间识别）。
	update_tasks	修改任务标题、内容、日期或优先级。
	complete_tasks	将任务标记为完成。
	delete_tasks	批量删除任务。
	create_subtasks	为任务添加子任务。
	move_tasks	在不同项目之间移动任务（支持批量）。
查询	query_tasks	高级清单查询（支持日期范围、优先级、搜索词）。
	get_completed_tasks	按项目和时间范围查询已完成的任务。
习惯	get_all_habits	获取所有习惯列表。
	get_habit	按 ID 查看单个习惯。
	create_habits	创建习惯（支持批量）。
	update_habits	原地修改习惯属性（支持批量）。
	checkin_habits	给习惯打卡，默认今天（支持批量与补打）。
	get_habit_checkins	按日期范围查询习惯的打卡记录。

📂 项目结构

ticktick-mcp-enhanced/
├── src/
│   └── ticktick_mcp/
│       ├── __init__.py          # 包入口
│       ├── server.py            # MCP 服务入口
│       ├── auth.py              # OAuth 逻辑与回调服务器
│       ├── client_manager.py    # 客户端管理
│       ├── log.py               # 日志配置
│       ├── ticktick_client.py   # TickTick API 客户端
│       ├── tools/               # 各类工具实现
│       │   ├── project_tools.py # 清单工具
│       │   ├── task_tools.py    # 任务工具
│       │   ├── query_tools.py   # 查询工具
│       │   ├── habit_tools.py   # 习惯工具
│       │   └── prompts/         # 工具描述 (.txt)
│       └── utils/               # 格式化与校验工具
├── pyproject.toml              # 项目配置与依赖
└── README.md                  # 本文档

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• Model Context Protocol
• 滴答清单 Open API
• FastMCP