TickTick MCP Server

A Model Context Protocol (MCP) server that provides integration with TickTick task management service.

Features

• List tasks and projects with enhanced display (human-readable priorities)

• Create, update, and delete tasks

• Mark tasks as completed

• Get specific task details

• Timezone handling with manual D+1 adjustment for accurate due date calculations

• Get overdue tasks with configurable timezone offset

• Get today's tasks with proper timezone compensation

• OAuth and username/password authentication support

• Full TypeScript support with proper error handling

Related MCP server: Tiny TODO MCP

Setup

1. Install dependencies:

2. Create environment configuration:

3. Configure authentication in .env:

Option A: OAuth (Recommended)

Option B: Username/Password

For OAuth setup, see OAUTH_SETUP.md or use the helper:

4. Build the project:

Usage

Development

Production

Available Tools

• get_tasks - Get all tasks or tasks from a specific project (with enhanced display)

• get_overdue_tasks - Get overdue tasks with timezone compensation (configurable offset, defaults to UTC+8 - adjust for your timezone)

• get_todays_tasks - Get tasks due today with D+1 timezone adjustment

• get_projects - Get all projects from TickTick

• create_task - Create a new task with priority, tags, due dates

• update_task - Update an existing task

• delete_task - Delete a task

• complete_task - Mark a task as completed

• get_task - Get a specific task by ID

Timezone Handling

This server includes manual timezone workarounds to handle TickTick's timezone inconsistencies:

• D+1 Adjustment: Due dates are automatically adjusted by adding 1 day to compensate for timezone differences

• Configurable Offset: get_overdue_tasks accepts a timezoneOffsetHours parameter

  • Default: 8 (UTC+8) - Change this for your timezone!

  • Examples:

    • timezoneOffsetHours: -5 for EST (UTC-5)

    • timezoneOffsetHours: 0 for UTC

    • timezoneOffsetHours: 9 for JST (UTC+9)

    • timezoneOffsetHours: 1 for CET (UTC+1)

• All-day vs Timed Tasks: Different handling for all-day tasks vs specific time tasks

• Enhanced Display: Tasks include human-readable priority text (None, Low, Medium, High)

Important: The default timezone offset is set to UTC+8. Make sure to specify your correct timezone offset when calling get_overdue_tasks to get accurate results for your location.

MCP Integration

Claude Desktop (with Claude Desktop app)

Add this server to your MCP client configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Cursor IDE

Add this server to your Cursor MCP configuration:

Location: Create/edit .cursorrules or Cursor settings for MCP servers

Alternative with Username/Password

License

MIT