chriswinsatlife/ticktick_mcp_v2

TickTick MCP V2

Enhanced TickTick MCP server with V2 API support for assignees, sections, comments, batch operations, and 35x performance improvement through checkpoint sync.

🚀 Features

V2 Enhanced Features

• Task Assignment - Assign tasks to specific team members
• Section Management - Organize tasks in kanban columns (New, In Progress, Future, Blocked)
• Tag Management - Categorize and filter tasks with tags
• Comments & Activity - Add timestamped comments and view task history
• Batch Operations - Efficient bulk task operations
• Checkpoint Sync - 35x performance improvement (1.1s vs 35s)
• Advanced Filtering - Filter by assignee, section, tags, priority

Requirements

• V2 session authentication is required
• V1 OAuth is not yet implemented

🔧 Setup

1. Configuration

cp .env_template .env
# Edit .env with your TickTick session token

Get session token from browser DevTools:

1. Open TickTick in browser, open DevTools (F12) → Network tab
2. Refresh page, find any api.ticktick.com request
3. Copy full Cookie header → TICKTICK_SESSION_TOKEN

2. Add to Cursor

Copy this JSON into your Cursor MCP config:

"ticktick_mcp_v2": {
  "command": "/Users/your_name/.local/bin/uv",
  "args": [
    "run",
    "--directory",
    "/Users/your_name/ticktick_mcp_v2",
    "-m",
    "main"
  ]
}

3. Switch to the server in Cursor

That's it. uv handles everything automatically.

🛠️ MCP Tools

Core Task Management

create_task

Create tasks with V2 enhancements:

create_task(
    title="Fix critical bug",
    project_id="cyhq",
    content="Details about the bug",
    assignee="carlos",           # V2: assign to team member
    section="in_progress",       # V2: set kanban section  
    priority="high",
    tags="urgent, bug-fix",      # V2: add tags
    due_date="2026-05-15T17:00:00.000+0000"
)

update_task

Comprehensive task updates:

update_task(
    task_id="67c1d244d3bd919605c39402",
    project_id="cyhq",
    content="Status update on the task",     # Append as comment
    assignee="ann",                          # V2: reassign
    section="blocked",                       # V2: move section
    status="complete"
)

get_tasks

Advanced filtering:

get_tasks(
    project_id="cyhq",
    assignee="carlos",           # V2: filter by assignee
    section="in_progress",       # V2: filter by section
    tags="urgent",               # V2: filter by tags
    priority="high",
    limit=50
)

Additional Tools

search_tasks

Search for tasks across projects using keywords:

search_tasks("Powerset meeting")
search_tasks("schedule", "cyhq")
search_tasks("Italian attorneys")

get_project_columns

Get column/section information for a project:

get_project_columns("cyhq")

V2 Advanced Features

The get_tasks and update_task tools provide all V2 functionality:

Filter by Assignee

get_tasks(assignee="carlos")
get_tasks(assignee="me")

Filter by Section

get_tasks(section="in_progress")
get_tasks(section="blocked")

Move Task to Section

update_task("task_id", section="blocked")

Assign Task to User

update_task("task_id", assignee="ann")

Add Comment to Task

update_task("task_id", add_comment="Working on this now")

Get Task Activity

get_task("task_id", include_activity=True)

Utility Features

Natural Date Parsing

Dates are automatically parsed in create_task and update_task:

create_task("Review docs", due_date="tomorrow at 2pm")
update_task("task_id", due_date="next friday")

🗂️ Project & User Mappings

Project Aliases

• cyhq, team, main, hq → CYHQ project (600ce43b08d35100aa47658c)
• inbox, personal, my_tasks → Personal inbox
• recurring, repeat → CYHQ Recurring (66b32defaf7e9165b805afd7)
• icebox, deferred → CYHQ Icebox (66b785a2b83b1105e028c330)

User Aliases

• carlos, cl → Carlos (ID: 117021928)
• ann, aj → Ann (ID: 126258410)
• chris, cy → Chris/CY (ID: 115949154)
• ai, ai_agent → AI Agent (ID: 123145261)

Section Aliases

• new, new_tasks, todo → New Tasks (6481e516ff78514b6c688124)
• in_progress, progress, active → In Progress (67c8248bce389a2a32d12487)
• future, backlog, later → Future Tasks (65f67cb1725bd1c72a547083)
• blocked, waiting, on_hold → Blocked (67cbba658c34d109b8053419)

⚡ Performance Optimization

Checkpoint Sync

V2 includes intelligent caching with checkpoint sync:

• 35x performance improvement (1.1s vs 35s for typical operations)
• Delta sync only fetches changes since last checkpoint
• Automatic fallback to full sync when needed
• Cache stored automatically

Batch Operations

Efficient bulk operations:

• Multiple task updates in single API call
• Optimized for team workflows
• Automatic cache invalidation

🔐 Authentication

Currently supports V2 session authentication only:

1. V2 Session Auth - Required for all features
2. V1 OAuth - Configuration prepared but not yet implemented

🏗️ Architecture

ticktick_mcp/
├── models/           # Pydantic data models
├── tools/            # MCP tool implementations
├── client_v2.py      # V2 session client
├── config.py         # Configuration and mappings
├── helpers.py        # Utilities and decorators
└── server.py         # MCP server instance

🐛 Troubleshooting

Common Issues

No V2 features available:

• Check TICKTICK_SESSION_TOKEN in .env
• Verify token is correct (get from browser DevTools)
• Check MCP server logs for authentication errors

Tasks not updating:

• Verify project IDs and task IDs
• Check user has permission to modify tasks
• Review assignee and section mappings

Performance issues:

• Check authentication is working correctly
• Monitor API rate limits

🙏 Acknowledgments

• Based on jen6_ticktick_mcp foundation
• Enhanced with V2 API research and optimization
• Built for TaskFactory team workflow optimization