Skip to content

About

MCP server for TickTick (ticktick.com / dida365.com) built on the private web API — cookie auth, full task/project/tag/habit/calendar coverage.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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

About

MCP server for TickTick (ticktick.com / dida365.com) built on the private web API — cookie auth, full task/project/tag/habit/calendar coverage.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages