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 adjustmentget_projects- Get all projects from TickTickcreate_task- Create a new task with priority, tags, due datesupdate_task- Update an existing taskdelete_task- Delete a taskcomplete_task- Mark a task as completedget_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_tasksaccepts atimezoneOffsetHoursparameter- Default: 8 (UTC+8) - Change this for your timezone!
- Examples:
timezoneOffsetHours: -5for EST (UTC-5)timezoneOffsetHours: 0for UTCtimezoneOffsetHours: 9for JST (UTC+9)timezoneOffsetHours: 1for 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