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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

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 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 -
13
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 -
3
TypeScript
Time Tools MCP Server
t-shiratori
A
security
A
license
A
quality
A Model Context Protocol server for time manipulation tasks, enabling AI models to get the current date/time and calculate duration between timestamps.
Last updated -
2
TypeScript
MIT License
Agentic Tools MCP Server
Pimzino
A
security
A
license
A
quality
A Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.
Last updated -
29
25
42
TypeScript
MIT License

View all related MCP servers

TickTick MCP Server