Ticktick Sdk

What dev-mirzabicer/ticktick-sdk MCP server does

The dev-mirzabicer/ticktick-sdk MCP server connects MCP-compatible AI assistants to TickTick. It exposes tools for reading and changing tasks, projects, folders, kanban columns, and tags. It also includes a tool for listing habits. The accompanying Python SDK provides asynchronous access to the same service and supports Dida365 as an additional API host.

Task operations include creation, retrieval, listing by status, updates, completion, deletion, project moves, parent-child relationships, text search, and pinning. Project and organization tools cover project details, folders, columns, and tag maintenance. The source description also identifies focus or Pomodoro data and user analytics as supported SDK areas, although the listed MCP tools do not enumerate separate tools for every one of those areas.

How it works

The dev-mirzabicer/ticktick-sdk MCP server combines two TickTick interfaces. OAuth2-backed V1 operations handle documented functionality, while an unofficial V2 session API supplies features such as tags, folders, habits, focus information, subtasks, and other web-app capabilities. The library chooses the appropriate API route for an operation.

MCP clients start the local server over standard input and output using the ticktick-sdk executable. Tool results can be formatted for people in Markdown or for programs in JSON, according to the README. Mutating task tools accept batches: creation, movement, and parent assignment support up to 50 items, while several update, completion, deletion, and pinning operations support up to 100.

Setup and configuration

Install the package with pip install ticktick-sdk. Python 3.11 or newer is required. A TickTick account is also required; the README notes that free and Pro accounts are supported.

Before starting the MCP server, register an application in the TickTick Developer Portal with the redirect URI http://127.0.0.1:8080/callback. Run ticktick-sdk auth with TICKTICK_CLIENT_ID and TICKTICK_CLIENT_SECRET to obtain an OAuth2 access token. The --manual option provides a text-based flow for headless or SSH environments.

Configure the server with TICKTICK_CLIENT_ID, TICKTICK_CLIENT_SECRET, TICKTICK_ACCESS_TOKEN, TICKTICK_USERNAME, and TICKTICK_PASSWORD. Claude Desktop configuration uses the ticktick-sdk command and these environment variables. The server can also target ticktick.com or dida365.com, and its CLI supports restricting enabled modules or tools.

Tools and capabilities

The listed MCP capabilities include:

• Create, inspect, list, update, complete, delete, move, search, and pin tasks.
• Assign or remove task parent relationships.
• List, create, update, and delete projects and folders.
• Manage kanban columns, including names and ordering.
• Create, update, delete, merge, and list tags.
• List habits.

The SDK additionally documents asynchronous HTTP operations, Pydantic v2 validation, focus or Pomodoro access, productivity statistics, and habit-management features. These SDK features should not be assumed to correspond to separately named MCP tools unless exposed by the installed version.

Limitations and notes

The V2 interface used for several advanced features is unofficial and reverse-engineered, so those capabilities depend on TickTick's web API behavior. OAuth application registration and token acquisition are required; this is not a credential-free connector. The README describes the project as MIT-licensed and lists Claude, GPT, and other MCP-compatible assistants as possible clients, while Claude Desktop has a documented configuration example.

The README and supplied tool list report different total MCP tool counts. For planning integrations, rely on the named tools and the installed package version rather than assuming a fixed total. Batch limits also vary by operation, so callers should validate the relevant tool's accepted range before sending large mutations.