TickTick MCP Server

An MCP server that lets your AI assistant manage your TickTick tasks, projects, habits, and more through natural language. Works with Claude Code, Cursor, VS Code, Claude Desktop, and any MCP-compatible client.

Also supports Dida365 (the Chinese version of TickTick).

---

Features

52 tools across two API layers:

Category	Tools	API
Projects	List, create, update, delete	V1
Tasks	CRUD, batch create, complete, subtasks	V1
Smart Queries	Due today/tomorrow/this week, overdue, by priority	V1
Search & Filter	Full-text search, multi-criteria filtering	V1
GTD Workflows	Engaged tasks, next actions, daily digest	V1
Tags	List, create, rename, delete, merge	V2
Habits	Create, check-in, view streaks and history	V2
Focus / Pomodoro	Heatmaps, time distribution, productivity score	V2
Completed Tasks	Browse finished tasks with date filtering	V2
Kanban Columns	Manage columns in kanban projects	V2
Project Folders	Organize projects into groups	V2
Task Organization	Move tasks between projects, subtask hierarchy	V2
User Profile	Profile info, timezone, settings	V2

V1 = Official TickTick Open API (OAuth2). V2 = Internal API (session auth) for features not in the public API.

---

Setup

1. Create a TickTick Developer App

1. Go to developer.ticktick.com/manage
2. Click + Create App
3. Set Redirect URI to: http://localhost:42813/callback
4. Note your Client ID and Client Secret

2. Install and Authenticate

git clone https://github.com/chrisvanek/ticktick-mcp-ratv.git
cd ticktick-mcp-ratv
npm install && npm run build

# Run the interactive setup wizard
node build/index.js auth

The wizard guides you through:

1. TickTick login (email + password) — enables V2 features (tags, habits, focus, completed tasks)
2. OAuth2 flow (Client ID + Secret + browser auth) — enables V1 features (projects, tasks)

Credentials are saved to a local .env file (excluded from git).

3. Connect to Your AI Client

Add the server to your MCP client config. Replace the placeholder values with the credentials from your .env file.

<details> <summary><strong>Claude Code</strong></summary>

CLI (recommended):

claude mcp add ticktick-mcp-server \
  node /absolute/path/to/ticktick-mcp-ratv/build/index.js \
  -e TICKTICK_CLIENT_ID=your_client_id \
  -e TICKTICK_CLIENT_SECRET=your_client_secret \
  -e TICKTICK_ACCESS_TOKEN=your_access_token \
  -e TICKTICK_REFRESH_TOKEN=your_refresh_token \
  -e TICKTICK_USERNAME=your_email \
  -e TICKTICK_PASSWORD=your_password \
  -e TICKTICK_DEVICE_ID=your_device_id \
  -s user

Use -s user (available everywhere), -s project (shared with team), or -s local (single project).

Config file (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Verify with /mcp in Claude Code.

</details>

<details> <summary><strong>Cursor</strong></summary>

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Restart Cursor after saving.

</details>

<details> <summary><strong>VS Code (Copilot Agent Mode)</strong></summary>

Requires VS Code 1.99+ with GitHub Copilot. Create .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Quit and relaunch Claude Desktop (Cmd+Q / Alt+F4).

</details>

<details> <summary><strong>Cline (VS Code extension)</strong></summary>

Open the Cline panel > MCP Servers icon > Configure, then add:

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

</details>

Dida365 (China)

Add TICKTICK_HOST=dida365 to your environment variables. This routes API calls to api.dida365.com.

Node Version Managers (nvm, fnm, etc.)

If node doesn't resolve in your MCP client, use the full path:

"command": "/Users/you/.nvm/versions/node/v22.0.0/bin/node"

---

Usage Examples

Once connected, just talk naturally. Here are examples organized by what you can do:

Morning Planning

"Give me my daily summary"

"What's overdue?"

"What do I have due this week?"

"Show me all high priority tasks"

Creating Tasks

"Create a task called 'Review PR #42' in my Work project, due tomorrow, high priority"

"Add a task 'Buy groceries' to Personal with subtasks: milk, eggs, bread, butter"

"Create a recurring task 'Weekly standup notes' every Monday in my Work project"

"Create these tasks in my Work project: Review design mockups, Update API docs, Fix login bug"

Managing Tasks

"Mark the 'Send invoice' task as complete"

"Move 'Design review' to my Work project"

"Make 'Write tests' a subtask of 'Ship v2'"

"What tasks did I complete last week?"

Search & Filter

"Search for any tasks mentioning 'budget'"

"Show me all medium priority tasks"

"What tasks are due in the next 3 days?"

"Show me all tasks in my Personal project that have a due date"

Projects

"List all my projects"

"Create a new project called 'Q2 Goals' with a kanban view"

"Show me everything in my Work project — tasks, columns, the works"

Tags

"Show me all my tags"

"Create a tag called 'urgent' with a red color"

"Rename the 'bug' tag to 'bugfix'"

"Merge the 'todo' tag into 'backlog'"

Habits

"What habits do I have?"

"Check in my 'Drink water' habit for today"

"Create a habit called 'Read' with a goal of 30 pages per day"

"Show my check-in history for all habits since January"

Focus & Productivity

"Show my focus time heatmap for this month"

"How is my focus time distributed across tags?"

"What are my productivity stats?"

Organization

"List my project folders"

"Create a folder called 'Side Projects'"

"Show the kanban columns in my Sprint project"

"What's in my trash?"

---

Environment Variables

Variable	Required	Description
TICKTICK_CLIENT_ID	Yes	OAuth2 Client ID from developer portal
TICKTICK_CLIENT_SECRET	Yes	OAuth2 Client Secret
TICKTICK_ACCESS_TOKEN	Yes	OAuth2 access token (set by auth wizard)
TICKTICK_REFRESH_TOKEN	No	OAuth2 refresh token (enables auto-renewal)
TICKTICK_USERNAME	Yes	Your TickTick email (for V2 API)
TICKTICK_PASSWORD	Yes	Your TickTick password (for V2 API)
TICKTICK_DEVICE_ID	Recommended	Stable 24-char hex device id for the V2 x-device header (see note below)
TICKTICK_HOST	No	ticktick (default) or dida365 for China

Security note: The V2 API requires your TickTick username and password. These are stored as environment variables and never logged or transmitted anywhere except directly to TickTick's authentication endpoint. The .env file is created with restricted permissions (owner-only read/write).

About TICKTICK_DEVICE_ID: The V2 internal API authenticates a "device" via the x-device request header. If the device id is empty or unrecognized, TickTick rejects the login with a misleading username_password_not_match error — even when your credentials are correct. The server sends a non-empty device id to avoid this. If you don't set TICKTICK_DEVICE_ID, a random 24-character hex id is generated automatically on each launch; setting a stable value is recommended so TickTick doesn't treat every restart as a brand-new device. Any 24-char hex string works — or reuse the id your TickTick web client already uses (browser DevTools → Application → Local Storage → deviceAnalyticsData.id).

---

All 52 Tools

<details> <summary><strong>Project Management</strong> (6 tools, V1)</summary>

Tool	Description
ticktick_get_projects	List all projects
ticktick_get_project	Get a project by ID
ticktick_get_project_data	Get project with tasks and columns
ticktick_create_project	Create a project
ticktick_update_project	Update project properties
ticktick_delete_project	Delete a project

</details>

<details> <summary><strong>Task Management</strong> (6 tools, V1)</summary>

Tool	Description
ticktick_get_task	Get a task by ID
ticktick_create_task	Create a task with all options
ticktick_update_task	Update task fields
ticktick_complete_task	Mark a task as done
ticktick_delete_task	Delete a task
ticktick_batch_create_tasks	Create multiple tasks at once

</details>

<details> <summary><strong>Smart Queries & GTD</strong> (12 tools, V1)</summary>

Tool	Description
ticktick_get_all_tasks	All undone tasks across all projects
ticktick_search_tasks	Full-text search
ticktick_get_tasks_due_today	Tasks due today
ticktick_get_tasks_due_tomorrow	Tasks due tomorrow
ticktick_get_tasks_due_this_week	Tasks due in 7 days
ticktick_get_tasks_due_in_days	Tasks due in N days
ticktick_get_overdue_tasks	Overdue tasks
ticktick_get_tasks_by_priority	Filter by priority
ticktick_filter_tasks	Advanced multi-criteria filter
ticktick_get_engaged_tasks	GTD "Engage" list
ticktick_get_next_tasks	GTD "Next" list
ticktick_daily_summary	Full daily digest

</details>

<details> <summary><strong>Tags</strong> (5 tools, V2)</summary>

Tool	Description
ticktick_get_tags	List all tags
ticktick_create_tag	Create a tag
ticktick_rename_tag	Rename a tag
ticktick_delete_tag	Delete a tag
ticktick_merge_tags	Merge one tag into another

</details>

<details> <summary><strong>Habits</strong> (6 tools, V2)</summary>

Tool	Description
ticktick_get_habits	List all habits
ticktick_get_habit_sections	Get habit sections
ticktick_create_habit	Create a habit
ticktick_delete_habit	Delete a habit
ticktick_checkin_habit	Check in to a habit
ticktick_get_habit_checkins	View check-in history

</details>

<details> <summary><strong>Focus / Pomodoro</strong> (3 tools, V2)</summary>

Tool	Description
ticktick_get_focus_heatmap	Focus time heatmap
ticktick_get_focus_distribution	Focus distribution by category
ticktick_get_productivity_stats	Productivity score and stats

</details>

<details> <summary><strong>Completed & Trashed Tasks</strong> (2 tools, V2)</summary>

Tool	Description
ticktick_get_completed_tasks	Browse completed tasks
ticktick_get_trashed_tasks	View deleted tasks

</details>

<details> <summary><strong>Task Organization</strong> (2 tools, V2)</summary>

Tool	Description
ticktick_move_task	Move task to a different project
ticktick_set_task_parent	Set/remove subtask relationship

</details>

<details> <summary><strong>Kanban & Folders</strong> (8 tools, V2)</summary>

Tool	Description
ticktick_get_columns	List kanban columns
ticktick_create_column	Create a column
ticktick_delete_column	Delete a column
ticktick_move_task_to_column	Move a task to another kanban column
ticktick_get_project_folders	List project folders
ticktick_create_project_folder	Create a folder
ticktick_delete_project_folder	Delete a folder
ticktick_move_project_to_folder	Move a list into/out of a folder

</details>

<details> <summary><strong>User & Settings</strong> (2 tools, V2)</summary>

Tool	Description
ticktick_get_user_profile	Profile, email, timezone, subscription
ticktick_get_user_settings	Account preferences

</details>

---

Reference

Task priority values: 0 = None, 1 = Low, 3 = Medium, 5 = High

Date format: yyyy-MM-dd'T'HH:mm:ssZ (e.g. 2025-03-15T09:00:00+0000)

Recurrence rules: Standard RRULE format (e.g. RRULE:FREQ=DAILY;INTERVAL=1)

---

Development

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm run clean     # Remove build output

Adding a Tool

1. Add your tool in the appropriate file under src/tools/
2. Use server.registerTool() with a Zod input schema
3. It's automatically available to all MCP clients

Architecture

src/
├── index.ts              # Entry point + auth CLI routing
├── config.ts             # Environment variable loader
├── client.ts             # V1 API client (OAuth2)
├── client-v2.ts          # V2 API client (session auth)
├── types.ts              # TypeScript interfaces
├── auth-cli.ts           # Interactive auth wizard
├── auth/oauth.ts         # OAuth2 flow implementation
└── tools/
    ├── project-tools.ts  # Project CRUD (V1)
    ├── task-tools.ts     # Task CRUD (V1)
    ├── smart-tools.ts    # Smart queries & GTD (V1)
    ├── tag-tools.ts      # Tag management (V2)
    ├── habit-tools.ts    # Habit tracking (V2)
    ├── focus-tools.ts    # Focus/Pomodoro stats (V2)
    ├── column-tools.ts   # Kanban columns (V2)
    ├── folder-tools.ts   # Project folders (V2)
    └── v2-task-tools.ts  # Completed tasks, move, user (V2)

Both API clients handle auth transparently — expired tokens are refreshed automatically on 401 responses.

---

Troubleshooting

Problem	Fix
"Missing required environment variable"	Run node build/index.js auth or set vars in your MCP config
"Token refresh failed" / 401 errors	Re-run node build/index.js auth
Server not showing in Claude Code	Use absolute paths, check with /mcp, try claude mcp remove + add
Server not showing in Cursor	Restart Cursor, check Output panel > MCP

---

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes and run npm run build
4. Open a pull request

---

License

MIT — see LICENSE.

Acknowledgments

• TickTick Open API
• Model Context Protocol
• Inspired by jacepark12/ticktick-mcp and jen6/ticktick-mcp