ticktick-mcp

A stdio MCP server that exposes the TickTick task API as 14 tools, for use from Claude Desktop or any MCP client.

It authenticates with a single bearer token from an environment variable, so there is no OAuth flow to run.

Requirements

• Node 18 or newer (fetch and the node:test runner are both assumed)

• A TickTick account

• A TickTick API access token. Register an application at developer.ticktick.com to obtain one. The server refuses to start without it.

Run it

The name ticktick-mcp on the public npm registry belongs to an unrelated package. Install from this repository, not from npm.

git clone https://github.com/nvkudva/ticktick-mcp.git
cd ticktick-mcp
npm install
TICKTICK_ACCESS_TOKEN=your_token_here npm start

The process stays in the foreground and prints nothing on success — an MCP server talks over stdio, so silence means it is waiting for a client.

To wire it into Claude Desktop, add this to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows), using the absolute path to your clone:

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp/bin/ticktick-mcp.js"],
      "env": { "TICKTICK_ACCESS_TOKEN": "your_token_here" }
    }
  }
}

Configuration

How it works

Three layers. src/client.js holds TickTickClient, whose single request() method does all URL assembly, auth, body serialisation and status handling against https://api.ticktick.com; every named method is a one-line delegate. src/tools/projects.js and src/tools/tasks.js export plain arrays of {name, description, inputSchema, handler} — six project tools and eight task tools. src/index.js loops over both arrays, converts each JSON Schema to a Zod shape and registers it with the MCP SDK, wrapping every handler in one try/catch. bin/ticktick-mcp.js is a shebang shim that imports src/index.js. There is no cache, no session and no persisted state beyond the token.

Task priority is 0 none, 1 low, 3 medium, 5 high. Task status is 0 active, 2 completed.

Status

Project and task CRUD (get_all_projects, get_project, get_project_data, create_project, update_project, delete_project, get_task, create_task, update_task, complete_task, delete_task) map to endpoints documented in the TickTick Open API.

Known gaps, as of 2026-09-07:

• ticktick_move_tasks, ticktick_get_completed_tasks and ticktick_filter_tasks call paths that are not in the documented Open API surface. They have not been confirmed to work against a live token and may return 404.

• zod is imported by src/index.js but is not declared in package.json. It resolves today only through npm hoisting of the SDK's own copy; pnpm or Yarn PnP will fail at import.

• The schema converter in src/index.js handles one level only. Nested shapes for items and moves are flattened to "array of anything", so those arguments are not validated before they reach TickTick.

• npm test runs live integration tests against a real account: it creates and deletes real projects and tasks, and errors without TICKTICK_ACCESS_TOKEN. Only the client constructor tests run offline. Do not run it against an account you care about.

• ticktick_delete_project and ticktick_delete_task are exposed with no confirmation step and no dry run. Deletion is permanent.

• Requests have no timeout, no retry and no 429 handling, so a slow upstream will hang a tool call.

License

No licence file yet — all rights reserved. package.json declares MIT, but the repository carries no licence text.