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

Setup

Install dependencies:

npm install

Create environment configuration:

cp .env.example .env

Configure authentication in .env:

Option A: OAuth (Recommended)

TICKTICK_ACCESS_TOKEN=your_oauth_access_token
TICKTICK_REFRESH_TOKEN=your_refresh_token
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret

Option B: Username/Password

TICKTICK_USERNAME=your_ticktick_username
TICKTICK_PASSWORD=your_ticktick_password

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

node oauth-helper.js

Build the project:

npm run build

Usage

Development

npm run dev

Production

npm start

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)

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor IDE

Add this server to your Cursor MCP configuration:

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

{
  "mcp": {
    "servers": {
      "ticktick": {
        "command": "node",
        "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
        "env": {
          "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
          "TICKTICK_REFRESH_TOKEN": "your_refresh_token", 
          "TICKTICK_CLIENT_ID": "your_client_id",
          "TICKTICK_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

Alternative with Username/Password

{
  "env": {
    "TICKTICK_USERNAME": "your_username",
    "TICKTICK_PASSWORD": "your_password"
  }
}

License

MIT

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

A Model Context Protocol server that integrates with TickTick task management service, allowing AI assistants to list, create, update, and complete tasks with proper timezone handling.

Related MCP Servers

MCP DateTime
odgrim
A
security
A
license
A
quality
A TypeScript server implementing the Model Context Protocol (MCP) that provides datetime and timezone information to AI agents and chat interfaces, allowing them to access current time in various timezones.
Last updated -
4
2
TypeScript
Mozilla Public License 2.0
MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
2
Python
Tiny TODO MCP
tkc
-
security
F
license
-
quality
A Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.
Last updated -
1
TypeScript
Task Manager MCP Server
tradesdontlie
-
security
A
license
-
quality
A Model Context Protocol server providing comprehensive task management capabilities with support for project organization, task tracking, and automatic PRD parsing into actionable items.
Last updated -
4
Python
MIT License

View all related MCP servers

TickTick MCP Server