Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

TickTick MCP connector

OAuth 2.1/DCR ProductivityProject Management

Connect to TickTick MCP. Manage tasks, projects, habits, and focus sessions in your TickTick account from AI workflows.

TickTick MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “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

    Section titled “Authorize and make your first call”
    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)

What you can do

Section titled “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

Section titled “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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique ID of the task. Get it from search_task or get_task_in_project.
title string required Text 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.

Name Type Required Description
tasks array required No 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.

Name Type Required Description
tasks array required No description.
ticktickmcp_complete_task # Mark a task as completed by projectId and taskId. 2 params

Mark a task as completed by projectId and taskId.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique 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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_ids array required No description.
ticktickmcp_create_column # Create a new Kanban column in a project. 2 params

Create a new Kanban column in a project.

Name Type Required Description
column string required No description.
project_id string required Unique 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.

Name Type Required Description
end_time string required End time of the focus session in ISO 8601 format, e.g. 2026-06-01T10:00:00+0000.
start_time string required Start time of the focus session in ISO 8601 format, e.g. 2026-06-01T09:00:00+0000.
type integer required Focus session type: 0 for Pomodoro, 1 for timer.
habit_id string optional Unique ID of the habit. Get it from list_habits.
note string optional Optional text note to attach to the focus session.
task_id string optional Unique 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.

Name Type Required Description
habit string required No description.
ticktickmcp_create_project # Create a new project (list) in TickTick. 6 params

Create a new project (list) in TickTick.

Name Type Required Description
name string required Display name for the project.
color string optional Hex color code for the project, e.g. #FF6B6B.
group_id string optional ID of the project group to place this project in.
kind string optional Project kind. Accepted values: TASK, NOTE.
sort_order integer optional Integer sort order for positioning the project in the list.
view_mode string optional Default 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.

Name Type Required Description
project_group string required No description.
ticktickmcp_create_tag # Create a new tag for labeling tasks. 1 param

Create a new tag for labeling tasks.

Name Type Required Description
tag string required No description.
ticktickmcp_create_task # Create a new task in a TickTick project. 1 param

Create a new task in a TickTick project.

Name Type Required Description
task string required No description.
ticktickmcp_delete_comment # Delete a comment from a task by comment ID. 3 params

Delete a comment from a task by comment ID.

Name Type Required Description
id string required Unique ID of the resource.
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique 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.

Name Type Required Description
focus_id string required Unique ID of the focus session.
type integer required Focus 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.

Name Type Required Description
project_group_id string required Unique 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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique 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.

Name Type Required Description
id string required Unique 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.

Name Type Required Description
filter string required No 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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique 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.

Name Type Required Description
focus_id string required Unique ID of the focus session.
type integer required Focus 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.

Name Type Required Description
from_time string required Start of the time range in ISO 8601 format.
to_time string required End of the time range in ISO 8601 format. Range must not exceed one month.
type integer required Focus 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.

Name Type Required Description
habit_id string required Unique 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.

Name Type Required Description
from_stamp integer required Start date as an integer date stamp, e.g. 20260101 for January 1 2026.
habit_ids array required No description.
to_stamp integer required End 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.

Name Type Required Description
project_id string required Unique 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.

Name Type Required Description
project_id string required Unique 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.

Name Type Required Description
task_id string required Unique 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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
task_id string required Unique 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.

Name Type Required Description
project_id string required Unique 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.

Name Type Required Description
search string required No 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).

Name Type Required Description
search string required No 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.

Name Type Required Description
query_command string optional Predefined time query. Accepted values: today, last24hour, last7day, tomorrow, nextWeek.
ticktickmcp_move_task # Move tasks to different projects. 1 param

Move tasks to different projects.

Name Type Required Description
moves array required No description.
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.

Name Type Required Description
query string required Search 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.

Name Type Required Description
column string required No description.
column_id string required Unique ID of the column. Get it from list_columns.
project_id string required Unique 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.

Name Type Required Description
habit string required No description.
habit_id string required Unique 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.

Name Type Required Description
project_id string required Unique ID of the project. Get it from list_projects.
closed string optional Whether the project is archived.
color string optional Hex color code for the project, e.g. #FF6B6B.
group_id string optional ID of the project group to place this project in.
kind string optional Project kind. Accepted values: TASK, NOTE.
name string optional Display name for the project.
sort_order string optional Integer sort order for positioning the project in the list.
view_mode string optional Default 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.

Name Type Required Description
project_group string required No description.
project_group_id string required Unique 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.

Name Type Required Description
task string required No description.
task_id string required Unique 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.

Name Type Required Description
checkin_data string required No description.
habit_id string required Unique ID of the habit. Get it from list_habits.