TickTick CLI

简体中文 | English

Agent-friendly CLI and MCP server for TickTick international and Dida365 domestic APIs.

TickTick MCP CLI is designed for both human operators and AI agents:

• Humans get readable terminal commands for projects, tasks, completed tasks, exports, OAuth, and diagnostics.
• AI agents get stable JSON output, explicit safety checks, deterministic command shapes, and an MCP server exposing the same core capabilities.

If you paste this repository link into an agent, the agent should be able to install the project, check authentication, list projects/tasks, and use the MCP tools by following this README alone.

What it does

TickTick MCP CLI provides a shared Python core with two thin frontends:

• CLI: ticktick-mcp-cli, legacy ticktask, and short alias tt.
• MCP server: ticktick-mcp and legacy ticktask-mcp for agent runtimes that support Model Context Protocol.

Supported service profiles:

• ticktick → https://api.ticktick.com
• dida365 → https://api.dida365.com

Current capabilities:

• OAuth credential setup and login.
• Optional OS keyring storage for OAuth client secret, access token, and refresh token.
• OAuth state + PKCE hardened authorization flow.
• Automatic access-token refresh when expires_at is near or past expiry.
• Project list, project data retrieval, create, update, and delete, with project kind/view-mode validation.
• Task list/search/natural-query/create/get/update/complete/delete/move, with due-date convenience parsing (today, tomorrow, next monday, YYYY-MM-DD).
• Agent-safe task creation idempotency keys to avoid duplicate remote tasks when retrying after interruptions.
• Task reminder set/clear and repeat/RRULE set/clear helpers.
• Dry-run guarded batch complete/delete/move operations.
• Tag filtering, smart filters (today, overdue, upcoming, high-priority, no-date), priority/status validation, and task tag add/remove.
• Checklist item/subtask add/update/complete/delete for CHECKLIST tasks.
• Completed-task listing through the official POST /open/v1/task/completed API.
• Task analytics for open/completed/overdue counts, project throughput, tag distribution, and priority distribution.
• Progress reporting that combines tasks, habits, and focus sessions into one scorecard.
• Conflict-safe retries for read-only API calls, including Retry-After handling for rate limits and transient 5xx responses.
• Structured error taxonomy for agents: category, retryable, and remediation hints accompany every error payload.
• Incremental sync/export state file for checkpointed task exports.
• Date/project backup files with Markdown, JSONL, CSV, or JSON outputs plus a manifest.
• Official habit list/get/create/update, habit check-in/history, and focus list/get/delete.
• Export tasks, completed tasks, or focus-session reports as json, jsonl, csv, or markdown.
• Redacted diagnostic bundles for support and agent handoff, with config/token secrets represented only as boolean *_configured flags.
• Read-only real API smoke check gated by TICKTASK_INTEGRATION=1.
• MCP tools and read-only MCP resources over the same core behavior.

Install

Option A: installer script

For a one-command setup with MCP server and keyring extras, run:

curl -fsSL https://raw.githubusercontent.com/GeekMai90/ticktick-mcp-cli/main/scripts/install.sh | sh

The script installs from this GitHub repository by default (ticktick-mcp-cli[mcp,keyring] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git) because the PyPI package name is not published yet. It prefers uv tool install and falls back to pipx install, then prints the same verification commands used by the docs:

ticktick-mcp-cli --version
ticktick-mcp-cli doctor --json
ticktick-mcp-cli auth status --json

Option B: GitHub npx wrapper for agents

Agent runtimes with Node.js can run the GitHub wrapper without a global npm registry package:

npx github:GeekMai90/ticktick-mcp-cli doctor --json
npx github:GeekMai90/ticktick-mcp-cli auth status --json
npx --package github:GeekMai90/ticktick-mcp-cli ticktick-mcp

The wrapper delegates to the Python package from this GitHub repository via uvx when available, with a python3 -m pipx run fallback. Default spec: ticktick-mcp-cli[mcp,keyring] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git. It does not store credentials.

Option C: install from GitHub directly

Use the repository source until the ticktick-mcp-cli package is published on PyPI:

uv tool install 'ticktick-mcp-cli[mcp,keyring] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git'
# or
pipx install 'ticktick-mcp-cli[mcp,keyring] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git'

If you do not need keyring support, use only the MCP extra:

uv tool install 'ticktick-mcp-cli[mcp] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git'
# or
pipx install 'ticktick-mcp-cli[mcp] @ git+https://github.com/GeekMai90/ticktick-mcp-cli.git'

Option D: use directly from a clone

git clone https://github.com/GeekMai90/ticktick-mcp-cli.git
cd ticktick-mcp-cli
uv sync --all-extras --dev
uv run ticktask --help
uv run tt --help

Option E: install from PyPI after publication

The project has release automation, but the ticktick-mcp-cli package is not available on PyPI until a maintainer publishes a release. After publication, these commands should work:

uv tool install ticktick-mcp-cli
# or
pipx install ticktick-mcp-cli

Then verify:

ticktick-mcp-cli --version
ticktick-mcp-cli doctor --json

Console scripts:

• ticktick-mcp-cli — main public CLI.
• ticktask — backward-compatible legacy CLI.
• tt — short CLI alias.
• ticktick-mcp — main public stdio MCP server.
• ticktask-mcp — backward-compatible legacy MCP server.

Quick start for humans

1. Initialize OAuth app credentials

Create a TickTick or Dida365 developer OAuth app, then store its credentials locally:

ticktask auth init \
  --service ticktick \
  --client-id "$TICKTICK_CLIENT_ID" \
  --client-secret "$TICKTICK_CLIENT_SECRET" \
  --redirect-uri "http://localhost:8080/callback"

For Dida365, use:

ticktask auth init \
  --service dida365 \
  --client-id "$DIDA365_CLIENT_ID" \
  --client-secret "$DIDA365_CLIENT_SECRET" \
  --redirect-uri "http://localhost:8080/callback"

Local config path:

ticktask config path

Do not commit local config files, client secrets, access tokens, or refresh tokens. For OS-managed secret storage, initialize auth with --token-storage keyring after installing the optional extra (pipx install 'ticktick-mcp-cli[keyring]' or uv tool install 'ticktick-mcp-cli[keyring]'); the JSON config then keeps only non-secret metadata while client secret/access/refresh tokens are stored in the system keyring.

2. Log in with OAuth

Start the local callback login flow:

ticktask auth login --service ticktick --local-server --json

This opens the browser and waits for one callback on the configured localhost redirect URI.

Manual browser flow:

ticktask auth login --service ticktick --no-browser --json

Open the returned authorization_url. After the provider redirects to your callback URL, complete login with either the full callback URL:

ticktask auth login \
  --service ticktick \
  --callback-url 'http://localhost:8080/callback?code=***&state=STATE' \
  --json

or with code + state:

ticktask auth login --service ticktick --code CALLBACK_CODE --state STATE --json

Check status:

ticktask auth status --json

3. Use tasks

ticktask project list
ticktask task list
ticktask today
ticktask add "Plan release" --project Inbox
ticktask task add "Plan release" --project Inbox --idempotency-key agent-run-123:create-plan-release --json
ticktask task search "release"
ticktask task query "high priority #agent release" --json
ticktask task list --tag agent --filter high-priority
ticktask task filter --tag agent --priority high
ticktask completed today
ticktask task analytics week --project Inbox --json

Mutating dangerous operations require exact IDs and explicit confirmation:

ticktask project update PROJECT_ID --name "Renamed" --json
ticktask project delete PROJECT_ID --yes --json
ticktask task complete TASK_ID --project-id PROJECT_ID --yes
ticktask task delete TASK_ID --project-id PROJECT_ID --yes
ticktask task move TASK_ID --from-project-id PROJECT_ID --to-project-id OTHER_PROJECT_ID
ticktask task reminder set TASK_ID --project-id PROJECT_ID --reminder TRIGGER:PT10M
ticktask task reminder clear TASK_ID --project-id PROJECT_ID
ticktask task repeat set TASK_ID --project-id PROJECT_ID --preset weekly
ticktask task repeat clear TASK_ID --project-id PROJECT_ID
ticktask task batch complete --task-id TASK_ID_1 --task-id TASK_ID_2 --project-id PROJECT_ID
ticktask task batch delete --task-id TASK_ID --project-id PROJECT_ID --execute --yes
ticktask task batch move --task-id TASK_ID --from-project-id PROJECT_ID --to-project-id OTHER_PROJECT_ID
ticktask task tag add TASK_ID agent --project-id PROJECT_ID
ticktask task tag remove TASK_ID agent --project-id PROJECT_ID
ticktask task item delete TASK_ID ITEM_ID --project-id PROJECT_ID --yes

Export examples:

ticktask export tasks --format jsonl --status all
ticktask export tasks --format csv --project Inbox
ticktask export completed --format markdown --from 2026-05-01 --to 2026-05-17
ticktask export focus --format csv --from 2026-01-01 --to 2026-01-30 --type 0

Analytics and progress examples:

ticktask task analytics today --json
ticktask task analytics week --project Inbox --json
ticktask task analytics --from 2026-05-01 --to 2026-05-17 --json
ticktask report progress week --project Inbox --json
ticktask report progress --from 2026-05-01 --to 2026-05-17 --focus-type 1 --json

Incremental sync/export examples:

ticktask sync state --json
ticktask sync mark tasks:all --timestamp 2026-05-01T00:00:00Z --json
ticktask sync export tasks --format jsonl --state-key tasks:all --status all --save-state --json

Diagnostic bundle example:

ticktask doctor bundle --output ./ticktask-diagnostics.zip --json

The diagnostic bundle is a ZIP containing diagnostics.json and report.md. It is designed for bug reports and agent handoff: config paths, active service, runtime, MCP buildability, and tool counts are included, while client secrets, access tokens, refresh tokens, OAuth state, and PKCE verifier values are never written.

Backup examples:

ticktask backup tasks --output-dir ~/ticktask-backups --format markdown,jsonl,csv --status all --json
ticktask backup tasks --output-dir ~/ticktask-backups --date 2026-05-17 --project Inbox --from 2026-05-01 --to 2026-05-17 --json

Backups are written under OUTPUT_DIR/YYYY-MM-DD/project-slug/ with a date-level manifest.json.

Quick start for AI agents

Agent operating contract

When using ticktask from an agent:

1. Prefer --json for all CLI commands that support it.
2. Branch on ok first, then on error.code when ok is false.
3. Never infer task/project IDs from names before mutations; list/search first, then use exact IDs.
4. Pass --yes only after verifying the exact target of complete or delete.
5. Treat TICKTASK_INTEGRATION=1 as permission to make read-only real API calls only.
6. Never print or commit OAuth client secrets, access tokens, refresh tokens, local config files, or .env files.

Stable JSON envelope

Success:

{"ok": true, "data": {}, "meta": {}}

Error:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human message",
    "hint": "Next step",
    "category": "validation",
    "retryable": false,
    "remediation": {
      "action": "fix_arguments",
      "command": "rerun with valid arguments",
      "safe_to_retry": false
    }
  }
}

Structured error categories include configuration, auth, api, lookup, validation, safety, and unexpected. Agents should branch on ok, then error.code; use retryable and remediation.safe_to_retry before retrying.

Agent-safe command sequence

# Discover state
ticktask doctor --json
ticktask doctor bundle --output ./ticktask-diagnostics.zip --json
ticktask auth status --json
ticktask project list --json
ticktask project create "Focus" --json
ticktask project update PROJECT_ID --name "Renamed" --json
ticktask project delete PROJECT_ID --yes --json

# Read tasks
ticktask task list --json
ticktask task list --status completed --from 2026-05-01 --to 2026-05-17 --json
ticktask task search "release" --json
ticktask task list --tag agent --filter high-priority --json
ticktask task filter --tag agent --priority high --json
ticktask task analytics week --json
ticktask report progress week --json
ticktask sync export tasks --format jsonl --state-key tasks:all --status all --json
ticktask backup tasks --output-dir ~/ticktask-backups --format markdown,jsonl --status all --json

# Mutate only after exact IDs are known
# For task creation retries, reuse the same --idempotency-key only with the same payload.
ticktask task add "Plan release" --project Inbox --idempotency-key agent-run-123:create-plan-release --json
ticktask task update TASK_ID --project-id PROJECT_ID --title "New title" --json
ticktask task complete TASK_ID --project-id PROJECT_ID --yes --json
ticktask task delete TASK_ID --project-id PROJECT_ID --yes --json
ticktask task tag add TASK_ID agent --project-id PROJECT_ID --json
ticktask task tag remove TASK_ID agent --project-id PROJECT_ID --json
ticktask task item add TASK_ID "Checklist item" --project-id PROJECT_ID --json
ticktask task item update TASK_ID ITEM_ID --project-id PROJECT_ID --title "Renamed" --status completed --json
ticktask task item complete TASK_ID ITEM_ID --project-id PROJECT_ID --json
ticktask task item delete TASK_ID ITEM_ID --project-id PROJECT_ID --yes --json

# Habits and focus
ticktask habit list --json
ticktask habit create "Read" --goal 1 --unit time --json
ticktask habit checkin HABIT_ID 20260101 --value 1 --json
ticktask habit history HABIT_ID --from 20260101 --to 20260131 --json
ticktask focus list --from 2026-01-01 --to 2026-01-30 --type 0 --json
ticktask focus delete FOCUS_ID --type 0 --yes --json

# Safe real-API smoke: skipped unless explicitly enabled
ticktask integration smoke --json
TICKTASK_INTEGRATION=1 ticktask integration smoke --service dida365 --json

MCP server

Install optional MCP dependencies when working from a clone:

uv sync --extra mcp
uv run ticktick-mcp

If installed as a tool, run:

ticktick-mcp

The MCP server uses stdio and exposes the same shared core behavior as the CLI. It also exposes read-only MCP resources for common agent planning context and reusable MCP prompt templates for common workflows.

For AI agents, start with ticktask_describe_tools to inspect descriptions, parameter enum hints, confirmation requirements, and examples. Use ticktask_cli_parity to map MCP tools back to CLI commands. Read ticktask://projects, ticktask://config, and ticktask://saved-views when you need project context, sanitized local configuration, or smart-filter presets without invoking a tool. Use the built-in prompt templates for daily planning, weekly reviews, safe cleanup, and exports.

When agents create tasks, pass idempotency_key to ticktask_create_task or --idempotency-key to ticktask task add. Reusing the same key with the same create arguments returns the cached task instead of creating a duplicate remote task; reusing the key with different arguments fails validation. Idempotency records are stored locally in idempotency.json next to the active config directory.

MCP tools:

• ticktask_describe_tools
• ticktask_cli_parity
• ticktask_doctor
• ticktask_diagnostic_bundle
• ticktask_auth_status
• ticktask_list_projects
• ticktask_create_project
• ticktask_update_project
• ticktask_delete_project
• ticktask_list_tasks
• ticktask_filter_tasks
• ticktask_search_tasks
• ticktask_create_task
• ticktask_complete_task
• ticktask_today
• ticktask_get_task
• ticktask_update_task
• ticktask_delete_task
• ticktask_move_task
• ticktask_batch_complete_tasks
• ticktask_batch_delete_tasks
• ticktask_batch_move_tasks
• ticktask_set_task_reminders
• ticktask_clear_task_reminders
• ticktask_set_task_repeat
• ticktask_clear_task_repeat
• ticktask_add_task_tag
• ticktask_remove_task_tag
• ticktask_add_checklist_item
• ticktask_update_checklist_item
• ticktask_complete_checklist_item
• ticktask_delete_checklist_item
• ticktask_completed
• ticktask_task_analytics
• ticktask_progress_report
• ticktask_list_habits
• ticktask_get_habit
• ticktask_create_habit
• ticktask_update_habit
• ticktask_checkin_habit
• ticktask_habit_checkins
• ticktask_list_focuses
• ticktask_get_focus
• ticktask_delete_focus
• ticktask_export_tasks
• ticktask_sync_state
• ticktask_mark_sync_state
• ticktask_sync_export_tasks
• ticktask_backup_tasks
• ticktask_export_focuses

MCP resources:

• ticktask://projects — read-only project list for planning and exact-ID lookup.
• ticktask://config — sanitized active service/profile configuration with secrets redacted.
• ticktask://saved-views — built-in smart-filter presets and equivalent MCP/CLI arguments.

MCP prompts:

• ticktask_daily_planning — plan today using project context and saved views.
• ticktask_weekly_review — review progress with task analytics, completed tasks, habits, and focus.
• ticktask_cleanup — identify stale tasks with dry-run batch operations first.
• ticktask_export — export, backup, or incrementally sync task data.

Real API integration smoke

The integration smoke command is safe by default:

ticktask integration smoke --json

It returns skipped: true unless explicitly enabled.

To run a read-only real API check:

TICKTASK_INTEGRATION=1 ticktask integration smoke --service dida365 --json

This only lists projects and returns project_count. It does not create, update, complete, move, or delete projects or tasks.

Development

git clone https://github.com/GeekMai90/ticktick-mcp-cli.git
cd ticktick-mcp-cli
uv sync --all-extras --dev
uv run pytest -q
uv run ticktick-mcp-cli --help
uv run ticktick-mcp-cli doctor --json
uv run --with 'mcp>=1.0' python -c 'from ticktask.mcp.server import build_server; build_server(); print("mcp_build_ok")'

Project notes:

• Keep CLI and MCP as thin frontends over ticktask.core.
• Preserve stable JSON envelopes for agent callers.
• Keep destructive actions explicit and ID-based.
• Do not commit OAuth secrets or local token files.

Documentation

• Docs Index
• Agent-First Quickstart
• Installation
• OAuth
• CLI Usage
• MCP Usage
• MCP Integration Examples for Claude Desktop, Hermes, Cursor, Claude Code, and OpenClaw
• Agent Usage
• Release Checklist
• Roadmap: competitive parity and best-in-class agent workflows
• Original Implementation Plan

Safety notes

• Local configuration is stored outside the repository by default.
• .env, token files, local config files, dist/, and build outputs are ignored by git.
• OAuth login uses state and PKCE.
• API calls auto-refresh expired or near-expired tokens when a refresh token is available.
• Read-only API calls retry transient rate-limit/server failures; mutating writes do not blind-retry to avoid duplicate changes.
• Task creation supports local idempotency keys; same key + same payload reuses the result, while same key + different payload is rejected.
• Completed-task listing intentionally omits projectIds for global queries to avoid missing Dida365 completed tasks.

License

MIT. See LICENSE.