TickTick MCP Server

Instructions

Implementation Reference

• src/index.ts:52-68 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name, description, and input schema for get_overdue_tasks
  { name: 'get_overdue_tasks', description: 'Get all overdue tasks (incomplete tasks past their due date)', inputSchema: { type: 'object', properties: { projectId: { type: 'string', description: 'Optional project ID to filter overdue tasks', }, timezoneOffsetHours: { type: 'number', description: 'Timezone offset in hours from UTC (e.g., 8 for UTC+8). Defaults to 8', }, }, }, },
• src/index.ts:236-246 (handler)

  MCP CallToolRequestSchema handler case for get_overdue_tasks: extracts args, calls TickTickClient.getOverdueTasks, returns JSON response
  case 'get_overdue_tasks': const timezoneOffsetHours = args?.timezoneOffsetHours as number || 8; const overdueTasks = await this.ticktickClient!.getOverdueTasks(args?.projectId as string, timezoneOffsetHours); return { content: [ { type: 'text', text: JSON.stringify(overdueTasks, null, 2), }, ], };
• src/ticktick-client.ts:225-230 (handler)

  Core handler in TickTickClient: fetches raw tasks, filters overdue using isTaskOverdue helper, enhances for display
  async getOverdueTasks(projectId?: string, timezoneOffsetHours: number = 8): Promise<any[]> { // Get raw tasks for filtering logic const allTasks = await this.getTasksRaw(projectId); const overdueTasks = allTasks.filter(task => isTaskOverdue(task, timezoneOffsetHours)); return overdueTasks.map(task => enhanceTaskForDisplay(task)); }
• src/ticktick-client.ts:75-110 (helper)

  Key helper function that implements overdue logic: checks if incomplete task's adjusted due date is past now, handling all-day and timezone adjustment
  function isTaskOverdue(task: TickTickTask, timezoneOffsetHours: number = 8): boolean { // If task is completed, it's not overdue if (task.completedTime) { return false; } // If no due date, it's not overdue if (!task.dueDate) { return false; } try { // Get current date/time const now = new Date(); // Parse due date and add 1 day to compensate for timezone difference const dueDate = new Date(task.dueDate); const adjustedDueDate = new Date(dueDate.getTime() + (24 * 60 * 60 * 1000)); // Add 1 day // If it's an all-day task, compare dates only if (task.allDay) { // Get today's date in YYYY-MM-DD format const today = now.toISOString().split('T')[0]; const adjustedDueDateStr = adjustedDueDate.toISOString().split('T')[0]; // Task is overdue if adjusted due date is before today return adjustedDueDateStr < today; } // For timed tasks, compare datetime directly return adjustedDueDate < now; } catch (error) { // If date parsing fails, assume not overdue return false; } }