TickTick MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'ticktickmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize TickTick MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'ticktickmcp_get_user_preference',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "ticktickmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize TickTick MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="ticktickmcp_get_user_preference",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Checkins upsert habit — Create or update check-in records for a habit by habitId
• Update task, project group, project — Update an existing task’s fields
• Search task — Search tasks by keyword and return matching taskId, title, and URL
• Task move, complete — Move tasks to different projects
• List undone tasks by time query, undone tasks by date, tags — List undone tasks using a predefined time query: today, last24hour, last7day, tomorrow, or nextWeek
• Get user preference, task in project, task by id — Get user preferences including timezone and display settings

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

ticktickmcp_add_comment#Add a plain-text comment (max 1024 characters) to a task.3 params▾

Add a plain-text comment (max 1024 characters) to a task.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

titlestringrequiredText content of the comment (plain text, max 1024 characters).

ticktickmcp_batch_add_tasks#Create multiple tasks in one request. Each task must include a title and projectId.1 param▾

Create multiple tasks in one request. Each task must include a title and projectId.

NameTypeRequiredDescription

tasksarrayrequiredNo description.

ticktickmcp_batch_update_tasks#Update multiple existing tasks in one request. Each task must include its taskId.1 param▾

Update multiple existing tasks in one request. Each task must include its taskId.

NameTypeRequiredDescription

tasksarrayrequiredNo description.

ticktickmcp_complete_task#Mark a task as completed by projectId and taskId.2 params▾

Mark a task as completed by projectId and taskId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_complete_tasks_in_project#Mark up to 20 tasks as completed in a project.2 params▾

Mark up to 20 tasks as completed in a project.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idsarrayrequiredNo description.

ticktickmcp_create_column#Create a new Kanban column in a project.2 params▾

Create a new Kanban column in a project.

NameTypeRequiredDescription

columnstringrequiredNo description.

project_idstringrequiredUnique ID of the project. Get it from list_projects.

ticktickmcp_create_focus#Create a focus session record. Type 0 = Pomodoro, type 1 = timer.6 params▾

Create a focus session record. Type 0 = Pomodoro, type 1 = timer.

NameTypeRequiredDescription

end_timestringrequiredEnd time of the focus session in ISO 8601 format, e.g. 2026-06-01T10:00:00+0000.

start_timestringrequiredStart time of the focus session in ISO 8601 format, e.g. 2026-06-01T09:00:00+0000.

typeintegerrequiredFocus session type: 0 for Pomodoro, 1 for timer.

habit_idstringoptionalUnique ID of the habit. Get it from list_habits.

notestringoptionalOptional text note to attach to the focus session.

task_idstringoptionalUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_create_habit#Create a new habit to track in TickTick.1 param▾

Create a new habit to track in TickTick.

NameTypeRequiredDescription

habitstringrequiredNo description.

ticktickmcp_create_project#Create a new project (list) in TickTick.6 params▾

Create a new project (list) in TickTick.

NameTypeRequiredDescription

namestringrequiredDisplay name for the project.

colorstringoptionalHex color code for the project, e.g. #FF6B6B.

group_idstringoptionalID of the project group to place this project in.

kindstringoptionalProject kind. Accepted values: TASK, NOTE.

sort_orderintegeroptionalInteger sort order for positioning the project in the list.

view_modestringoptionalDefault view mode. Accepted values: list, kanban, timeline.

ticktickmcp_create_project_group#Create a new project group for organizing projects.1 param▾

Create a new project group for organizing projects.

NameTypeRequiredDescription

project_groupstringrequiredNo description.

ticktickmcp_create_tag#Create a new tag for labeling tasks.1 param▾

Create a new tag for labeling tasks.

NameTypeRequiredDescription

tagstringrequiredNo description.

ticktickmcp_create_task#Create a new task in a TickTick project.1 param▾

Create a new task in a TickTick project.

NameTypeRequiredDescription

taskstringrequiredNo description.

ticktickmcp_delete_comment#Delete a comment from a task by comment ID.3 params▾

Delete a comment from a task by comment ID.

NameTypeRequiredDescription

idstringrequiredUnique ID of the resource.

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_delete_focus#Delete a focus session record by focusId and type.2 params▾

Delete a focus session record by focusId and type.

NameTypeRequiredDescription

focus_idstringrequiredUnique ID of the focus session.

typeintegerrequiredFocus session type: 0 for Pomodoro, 1 for timer.

ticktickmcp_delete_project_group#Delete a project group permanently by its ID.1 param▾

Delete a project group permanently by its ID.

NameTypeRequiredDescription

project_group_idstringrequiredUnique ID of the project group. Get it from list_project_groups.

ticktickmcp_delete_task#Permanently delete a task by projectId and taskId.2 params▾

Permanently delete a task by projectId and taskId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_fetch#Fetch the full contents of a task by its ID.1 param▾

Fetch the full contents of a task by its ID.

NameTypeRequiredDescription

idstringrequiredUnique ID of the resource.

ticktickmcp_filter_tasks#Filter tasks by date range, project IDs, priority, tags, kind, or status.1 param▾

Filter tasks by date range, project IDs, priority, tags, kind, or status.

NameTypeRequiredDescription

filterstringrequiredNo description.

ticktickmcp_get_comment#Get all comments for a task by projectId and taskId.2 params▾

Get all comments for a task by projectId and taskId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_get_focus#Get a single focus session record by focusId and type.2 params▾

Get a single focus session record by focusId and type.

NameTypeRequiredDescription

focus_idstringrequiredUnique ID of the focus session.

typeintegerrequiredFocus session type: 0 for Pomodoro, 1 for timer.

ticktickmcp_get_focuses_by_time#Get focus sessions within a time range (max one month) filtered by type.3 params▾

Get focus sessions within a time range (max one month) filtered by type.

NameTypeRequiredDescription

from_timestringrequiredStart of the time range in ISO 8601 format.

to_timestringrequiredEnd of the time range in ISO 8601 format. Range must not exceed one month.

typeintegerrequiredFocus session type: 0 for Pomodoro, 1 for timer.

ticktickmcp_get_habit#Get details of a habit by habitId.1 param▾

Get details of a habit by habitId.

NameTypeRequiredDescription

habit_idstringrequiredUnique ID of the habit. Get it from list_habits.

ticktickmcp_get_habit_checkins#Get habit check-ins for one or more habits within a date range.3 params▾

Get habit check-ins for one or more habits within a date range.

NameTypeRequiredDescription

from_stampintegerrequiredStart date as an integer date stamp, e.g. 20260101 for January 1 2026.

habit_idsarrayrequiredNo description.

to_stampintegerrequiredEnd date as an integer date stamp, e.g. 20260630 for June 30 2026.

ticktickmcp_get_project_by_id#Get project details by projectId.1 param▾

Get project details by projectId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

ticktickmcp_get_project_with_undone_tasks#Get a project and all its undone tasks by projectId.1 param▾

Get a project and all its undone tasks by projectId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

ticktickmcp_get_task_by_id#Get full task details by taskId.1 param▾

Get full task details by taskId.

NameTypeRequiredDescription

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_get_task_in_project#Get a specific task by projectId and taskId.2 params▾

Get a specific task by projectId and taskId.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_get_user_preference#Get user preferences including timezone and display settings.0 params▾

Get user preferences including timezone and display settings.

ticktickmcp_list_columns#List all Kanban columns in a project.1 param▾

List all Kanban columns in a project.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

ticktickmcp_list_completed_tasks_by_date#List completed tasks filtered by project IDs and date range.1 param▾

List completed tasks filtered by project IDs and date range.

NameTypeRequiredDescription

searchstringrequiredNo description.

ticktickmcp_list_countdowns#List all countdown tasks for the current user.0 params▾

List all countdown tasks for the current user.

ticktickmcp_list_habit_sections#List all habit sections for the current user.0 params▾

List all habit sections for the current user.

ticktickmcp_list_habits#List all habits for the current user.0 params▾

List all habits for the current user.

ticktickmcp_list_project_groups#List all project groups for the current user.0 params▾

List all project groups for the current user.

ticktickmcp_list_projects#List all projects for the current user.0 params▾

List all projects for the current user.

ticktickmcp_list_tags#List all tags for the current user.0 params▾

List all tags for the current user.

ticktickmcp_list_undone_tasks_by_date#List undone tasks within a date range (max 14 days between start and end).1 param▾

List undone tasks within a date range (max 14 days between start and end).

NameTypeRequiredDescription

searchstringrequiredNo description.

ticktickmcp_list_undone_tasks_by_time_query#List undone tasks using a predefined time query: today, last24hour, last7day, tomorrow, or nextWeek.1 param▾

List undone tasks using a predefined time query: today, last24hour, last7day, tomorrow, or nextWeek.

NameTypeRequiredDescription

query_commandstringoptionalPredefined time query. Accepted values: today, last24hour, last7day, tomorrow, nextWeek.

ticktickmcp_move_task#Move tasks to different projects.1 param▾

Move tasks to different projects.

NameTypeRequiredDescription

movesarrayrequiredNo description.

ticktickmcp_search#Search TickTick and return matching results with IDs, titles, and URLs.1 param▾

Search TickTick and return matching results with IDs, titles, and URLs.

NameTypeRequiredDescription

querystringrequiredSearch keyword to filter tasks by name or content.

ticktickmcp_search_task#Search tasks by keyword and return matching taskId, title, and URL.1 param▾

Search tasks by keyword and return matching taskId, title, and URL.

NameTypeRequiredDescription

querystringrequiredSearch keyword to filter tasks by name or content.

ticktickmcp_update_column#Update an existing Kanban column by columnId.3 params▾

Update an existing Kanban column by columnId.

NameTypeRequiredDescription

columnstringrequiredNo description.

column_idstringrequiredUnique ID of the column. Get it from list_columns.

project_idstringrequiredUnique ID of the project. Get it from list_projects.

ticktickmcp_update_habit#Update an existing habit by habitId.2 params▾

Update an existing habit by habitId.

NameTypeRequiredDescription

habitstringrequiredNo description.

habit_idstringrequiredUnique ID of the habit. Get it from list_habits.

ticktickmcp_update_project#Update an existing project's name, color, group, or display settings.8 params▾

Update an existing project's name, color, group, or display settings.

NameTypeRequiredDescription

project_idstringrequiredUnique ID of the project. Get it from list_projects.

closedstringoptionalWhether the project is archived.

colorstringoptionalHex color code for the project, e.g. #FF6B6B.

group_idstringoptionalID of the project group to place this project in.

kindstringoptionalProject kind. Accepted values: TASK, NOTE.

namestringoptionalDisplay name for the project.

sort_orderstringoptionalInteger sort order for positioning the project in the list.

view_modestringoptionalDefault view mode. Accepted values: list, kanban, timeline.

ticktickmcp_update_project_group#Update an existing project group by projectGroupId.2 params▾

Update an existing project group by projectGroupId.

NameTypeRequiredDescription

project_groupstringrequiredNo description.

project_group_idstringrequiredUnique ID of the project group. Get it from list_project_groups.

ticktickmcp_update_task#Update an existing task's fields. To remove a parent-child relationship, set parentId to empty string.2 params▾

Update an existing task's fields. To remove a parent-child relationship, set parentId to empty string.

NameTypeRequiredDescription

taskstringrequiredNo description.

task_idstringrequiredUnique ID of the task. Get it from search_task or get_task_in_project.

ticktickmcp_upsert_habit_checkins#Create or update check-in records for a habit by habitId.2 params▾

Create or update check-in records for a habit by habitId.

NameTypeRequiredDescription

checkin_datastringrequiredNo description.

habit_idstringrequiredUnique ID of the habit. Get it from list_habits.