ticktick

This TickTick MCP Server exposes a set of endpoints that wrap the TickTick API, enabling you to manage tasks and projects within TickTick from your own applications or automation scripts. Core capabilities include creating, reading, updating, and deleting tasks and projects, handling subtasks, and marking tasks complete. The server also supports OAuth 2.0 authentication for secure access, and returns task and project objects that conform to the TickTickTaskSchema and TickTickProjectSchema defined in the project types. Typical usage involves authenticating with an access token and then invoking tools such as get_task_by_ids, create_task, update_task, complete_task, delete_task, get_user_projects, get_project_by_id, get_project_with_data, create_project, update_project, and delete_project to perform common project management workflows. The API design mirrors TickTick semantics (projects, tasks, subtasks, reminders, due dates, priorities, and recurrence rules), making it straightforward to integrate with dashboards, automation pipelines, or iCal-based reminders.

Prerequisites:

• Node.js (LTS) installed on your system
• Git available to clone the repository
• Basic knowledge of environment variable management

Install steps:

1. Clone the repository git clone https://github.com/your/repo.git cd repo

2. Install dependencies npm install

3. Configure environment variables Create a .env file or export vars in your environment. Required values:

   • TICKTICK_CLIENT_ID: Your TickTick OAuth client ID
   • TICKTICK_CLIENT_SECRET: Your TickTick OAuth client secret
   • TICKTICK_ACCESS_TOKEN: The generated access token for API access

   Example .env: TICKTICK_CLIENT_ID="<YOUR_CLIENT_ID>" TICKTICK_CLIENT_SECRET="<YOUR_CLIENT_SECRET>" TICKTICK_ACCESS_TOKEN="<ACCESS_TOKEN>"

4. Run the server npm run start or node src/server.js

5. (Optional) Run in development with hot-reload (if configured) npm run dev

6. Verify by querying the exposed endpoints or using any API client (e.g., curl or Postman)

Notes:

• Ensure the TickTick application credentials are valid and have the required scopes.
• If you rotate tokens, update TICKTICK_ACCESS_TOKEN accordingly.

Tips and common issues:

• Ensure environment variables are loaded before starting the server; a missing or invalid access token will cause authentication failures.
• When creating tasks, you can provide iCalendar formatted reminders and RFC 5545 recurrence rules for repeat tasks. ISO 8601 task dates are required (yyyy-MM-dd'T'HH:mm:ssZ).
• If you encounter OAuth-related errors, double-check that the Redirect URI configured in TickTick matches what your application expects (as noted in Setup: http://localhost:8000/callback).
• The get_project_with_data endpoint can be used to fetch a project along with its tasks and columns in a single call, which is efficient for building project dashboards.
• For debugging, enable verbose logging if your server supports a DEV log level and monitor for any 4xx/5xx responses to quickly identify misconfigurations.