partymola/ticktick-mcp

MCP server for TickTick task management. Create, update, complete, move, and filter tasks via the TickTick v2 API, with field-preserving updates, day-of-week date validation, read-after-write verification, and idempotent completion tracking.
Designed for Claude Code and other MCP clients.
Unofficial. Not affiliated with TickTick Ltd. Built on ticktick-py (MIT).
Features
- **Full task lifecycle** - create, update, complete, move, subtask, and delete
- **Field-preserving updates** - ticktick_update_task re-fetches the task and overlays only the fields you set, so the API never wipes the ones you omit
- **Day-of-week validation** - any call that sets a date must confirm the weekday, catching off-by-one date mistakes before they reach the server
- **Read-after-write verification** - create/update re-read the task and surface _verification_warnings when the server echo doesn't match
- **Compact listing** - list tools return a trimmed view by default so large projects stay under the MCP result-size cap (see below)
- **Fresh reads** - read tools re-sync server state on demand, so edits made from the TickTick app on other devices show up without a restart
- **Completion tracking** - mark completed tasks as processed so an agent reviews each one exactly once, and completions made through this server record themselves
Requirements
- Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)
- uv (recommended - see the install note below)
- A TickTick account
- A registered TickTick app for OAuth credentials (free - developer.ticktick.com)
Install
This creates a .venv and installs from uv.lock, giving you the console script at .venv/bin/ticktick-mcp, or .venv\Scripts\ticktick-mcp on Windows. Every command below names it the POSIX way.
pip install . works too. The fork of ticktick-py this server needs is pinned as a direct git reference inside dependencies, which pip and uv both honour; uv sync is recommended because it installs the exact versions in uv.lock rather than re-resolving them.
Credentials
TickTick sign-in needs two things: an OAuth app (client ID + secret) and your own account login.
1. Register an app at developer.ticktick.com. Set the **Redirect URI** to http://localhost:8080/redirect. Note the **Client ID** and **Client Secret**.
2. Copy the template into the directory the server reads, and fill it in:
3. This file holds your account password in plain text, and the server does not create it, so tighten it yourself. On POSIX:
Those are POSIX mode bits, and on Windows they do nothing: access there follows the ACLs the file inherits from its parent directory. No Windows equivalent of the two commands is documented here.
The two token files beside it are created owner-only, and a config directory the server creates is too - but one it finds already there is left as it is. Those are POSIX modes as well, set on Windows too, where they do not narrow who may read what.
**Authorise once, at a terminal, before registering the server:**
It opens a browser and asks you to paste back the URL you land on, then exits. The token is cached next to your .env as .token-oauth, and every later start reuses it. TickTick issues no refresh token, so this recurs when the token expires - run the same command again.
Do not let that step happen inside the MCP server. The prompt reads from standard input, which for a stdio server is the JSON-RPC channel, so an unauthorised first tool call opens a browser on the host and blocks. In a container it cannot be completed at all - run auth on the host and mount the config directory in.
The username/password half needs no separate step: the server logs in lazily on the first tool call and caches that session token as .token-v2, so it does not re-submit your credentials on every start.
The server looks for .env in this order: the --dotenv-dir argument, then the TICKTICK_MCP_DOTENV_DIR environment variable, then ~/.config/ticktick-mcp/. If no .env is found it falls back to the TICKTICK_* environment variables directly, which is convenient for container/CI use.
Privacy and the unofficial API
Your TickTick credentials live only in your local .env (or the environment) and are sent only to TickTick's own servers - never to the developer or any third party. The server reads and writes only your own account.