Ticktick MCP server

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 - ticktickupdatetask 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 verificationwarnings 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

git clone https://github.com/partymola/ticktick-mcp
cd ticktick-mcp
uv sync

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:

mkdir -p ~/.config/ticktick-mcp && cp .env.example ~/.config/ticktick-mcp/.env

TICKTICK_CLIENT_ID=your_client_id
   TICKTICK_CLIENT_SECRET=your_client_secret
   TICKTICK_REDIRECT_URI=http://localhost:8080/redirect
   TICKTICK_USERNAME=your_ticktick_email
   TICKTICK_PASSWORD=your_ticktick_password

1. This file holds your account password in plain text, and the server does not create it, so tighten it yourself. On POSIX:

chmod 700 ~/.config/ticktick-mcp
   chmod 600 ~/.config/ticktick-mcp/.env

Shortened. The full README is on GitHub.