ticktick-mcp

MCP server for TickTick / 滴答清单 (and Dida365 / 滴答清单 CN), built on the private web API — the same endpoints the web app at ticktick.com/webapp calls — not the small public Open API. The outcome of a reverse-engineering session against the 2026 web bundle (full findings: docs/reverse-engineering.md).

TypeScript + Node.js (@modelcontextprotocol/sdk), stdio transport, no native dependencies. Auth is a browser session cookie, so the server sees exactly what the signed-in web app sees: every project, task, tag, habit and calendar.

Why not the Open API

TickTick publishes /open/v1 (see docs/open-api.md). It is Bearer-authenticated, stable, and tiny — no tags, no search, no habits, no calendar, no trash, no batch delete. The private /api/v2 + /api/v3 surface this server uses has ~164 usable endpoints on a real account (measured — see the findings doc). The trade-off is honesty: those endpoints are undocumented and move with the web app.

Tools

34 tools. Every one below was exercised against a live account during development.

| Tool | What it does | |---|---| | list_tasks | Tasks in a project (projectId: "inbox" resolves the inbox) | | get_task | A single task by id | | create_task | Create a task (title, dates, priority, tags, recurrence, subtasks) | | update_task | Patch fields on a task | | complete_task / uncomplete_task | Set status 2 / 0 | | delete_task | Trash a task, or forever: true to hard-delete | | move_task | Move a task between projects | | list_completed_tasks | Completed tasks by date range, one project or all | | list_trash / restore_task | Trash listing and restore | | batch_tasks | Add/update/delete many tasks at once¹ | | search_tasks | Full-text search | | list_projects / get_project | Projects (lists) | | create_project / update_project / delete_project | Project lifecycle | | list_tags / rename_tag / merge_tags / delete_tag | Tags | | list_columns | Kanban columns | | get_current_user | Profile: id, inbox id, plan | | sync_check | Offline-first delta pull of the whole account | | get_preferences | User preferences | | list_templates / list_countdowns | Templates, countdowns | | list_habits / list_habit_sections / query_habit_checkins | Habits | | list_calendar_accounts / list_calendar_subscriptions / list_calendar_events | Calendars |

¹ Some accounts are gated: POST /api/v2/batch/task answers 403 access_forbidden. The tool reports that plainly instead of hiding it.

Install

npm install -g @powercess/ticktick-mcp     # or: npx @powercess/ticktick-mcp

From a source checkout:

npm install
npm run build
npm test                                   # hermetic unit tests, no credentials
node scripts/smoke-client.mjs list_projects '{}'

Configure as an MCP server:

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@powercess/ticktick-mcp"],
      "env": {
        "TICKTICK_COOKIE": "t=<session cookie>; _csrf_token=<csrf>; ap_user_id=<id>"
      }
    }
  }
}

Authentication

Two credential types, auto-detected from shape — no mode flag needed:

| Credential | Env var | API surface | Tools | |---|---|---|---| | Web session cookie | TICKTICK_COOKIE | private /api/v2 + /api/v3 | all 36 | | Personal API token (tp_…) | TICKTICK_API_TOKEN | official /open/v1 | ~28 (stable subset) |

Precedence: tool argument → environment → ~/.ticktick-mcp/credentials.json.

Web session cookie (full feature set)

Grab it from a logged-in browser — DevTools → Network → any api.ticktick.com request → Request Headers → cookie — and pass the whole value.

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@powercess/ticktick-mcp"],
      "env": {
        "TICKTICK_COOKIE": "t=<session cookie>; _csrf_token=<csrf>; ap_user_id=<id>"
      }
    }
  }
}

Personal API token (no cookie, stable)

Create one in the web app: Settings → Account → API Token → Create. Long-lived, no 2FA prompt, no browser required.

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@powercess/ticktick-mcp"],
      "env": {
        "TICKTICK_API_TOKEN": "tp_<your token>"
      }
    }
  }
}

Token mode covers projects, tasks (CRUD, complete, move, batch, completed, search), tags, columns, habits, focus, countdowns and project groups — about 28 of the 36 tools. Web-only tools (sync_check, trash, templates, calendar, preferences, tag rename/merge/delete) return a clear error explaining that a cookie session is needed.

See docs/authentication.md for the full walkthrough, Dida365 setup and every supported input.

Layout

src/config.ts      credential resolution (env → file), site selection
src/client.ts      HTTP client: cookie + x-csrftoken, JSON, typed errors
src/api.ts         endpoint functions (sync, projects, tasks, tags, habits, calendar)
src/errors.ts      TickTickError + human-readable formatting
src/tools/*.ts     MCP tool surface (tasks, projects, account)
src/index.ts       server bootstrap
scripts/           smoke-client.mjs
test/              node:test suites (hermetic)
docs/              reverse-engineering findings, auth guide, Open API notes

Limitations (honest)

• Undocumented and unstable. These endpoints are what the web app happens to call today; TickTick can change them without notice. The sync_check checkpoint format and the x-csrftoken requirement are reverse-engineered, not promised.
• Session cookies expire. There is no OAuth refresh here — when the cookie dies, refresh it by hand. (The official Open API is the right choice if you need long-lived tokens.)
• Batch writes are account-gated. batch_tasks may 403 on your account.
• Not every endpoint is wired. ~164 are usable; the tools cover the common read/write surface. Rarer ones (team collaboration, calendar OAuth handshakes, MFA, account merge) are deliberately out of scope — see the findings doc.
• A few endpoints need a full object, not a patch. update_project merges the current project before writing for exactly this reason.
• No rate-limit handling. TickTick may throttle; the server surfaces the error.

Privacy

The session cookie is a live credential for the whole account. It lives in ~/.ticktick-mcp/credentials.json (mode 0600, gitignored) or the environment, never in the package directory. Captured traffic, cookies and account ids are never committed. Revoke by logging out of the web app (or rotating the session).

License

MIT