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:

Open TickTick in browser, open DevTools (F12) → Network tab
Refresh page, find any api.ticktick.com request
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:

V2 Session Auth - Required for all features
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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

Enhanced TickTick task management server that provides rich functionality including task assignment, section management, comments, and batch operations with significantly improved performance through checkpoint sync.

Related MCP Servers

MCP Orchestrator Server
mokafari
-
security
A
license
-
quality
A server for task orchestration and coordination, facilitating task management with dependencies, multi-instance collaboration, and persistent task tracking.
Last updated -
7
22
JavaScript
MIT License
MCP TODO Checklist Server
hevener10
A
security
F
license
A
quality
A server that implements a checklist management system with features like task creation, progress tracking, data persistence, and item comments.
Last updated -
5
3
TypeScript
DeltaTask MCP Server
brysontang
A
security
A
license
A
quality
Provides API access to a locally-hosted task management system with features for creating, updating, and organizing tasks, including support for urgency levels, effort estimates, subtasks, and bi-directional sync with Obsidian markdown files.
Last updated -
12
7
Python
MIT License
TickTick MCP Server
jen6
-
security
F
license
-
quality
An MCP server that enhances TickTick workflow by providing comprehensive task management tools with improved filtering capabilities, allowing AI assistants and MCP-compatible applications to interact with TickTick tasks with greater precision.
Last updated -
24
Python

View all related MCP servers