TickTick MCP Server (Python)

A robust MCP server for TickTick based on the ticktick-py library.

Features

• Full task management: Create, list, update, complete, and delete tasks
• Advanced filtering: Filter tasks by priority, due date, and status
• Reminders: Set multiple reminders with RFC 5545 trigger format
• Subtasks: Create and complete checklist items within tasks
• Date/time support: Separate start and due dates with optional times
• Timezone support: Specify timezone for time-sensitive tasks
• Recurrence: Full RRULE support for recurring tasks
• Smart matching: Fuzzy, partial, or exact title matching
• Direct ID lookup: Skip title search when task ID is known
• Retry logic: Automatic retry on transient failures
• OAuth2 authentication via ticktick-py
• V2 API features (optional): Completed tasks, Inbox, tags, and search

Available MCP Tools

Task Management

Tool	Description
create_task	Create a new task with optional reminders, subtasks, dates, timezone
list_tasks	List tasks with optional filters (project, priority, due, status)
get_task	Retrieve a single task by ID
update_task	Update task properties (title, dates, reminders, subtasks, etc.)
complete_task	Mark a task as complete
delete_task	Delete a task

Subtask Management

Tool	Description
add_subtask	Add a subtask/checklist item to an existing task
complete_subtask	Mark a subtask as complete

Project Management

Tool	Description
list_projects	List all projects/lists

GTD (Getting Things Done) Tools

Dedicated tools for GTD productivity workflows:

Tool	Description
gtd_get_engaged_tasks	Tasks needing immediate attention (high priority, due today, or overdue)
gtd_get_next_tasks	Tasks for your next work session (medium priority or due tomorrow)
gtd_get_weekly_review	All tasks grouped by urgency for weekly planning
gtd_get_someday_tasks	Tasks without dates or priority (ideas for later)

GTD Workflow Example:

# Morning: Check what needs attention NOW
gtd_get_engaged_tasks()
# Shows: High priority tasks, tasks due today, overdue tasks

# After clearing engaged items: What's next?
gtd_get_next_tasks()
# Shows: Medium priority tasks, tasks due tomorrow

# Weekly planning session
gtd_get_weekly_review()
# Shows: Overdue (0) / Today (3) / This Week (5) / No Date (12)

# Periodically review ideas
gtd_get_someday_tasks()
# Shows: Tasks without dates, grouped by project

Common Parameters

Dates: Use YYYY-MM-DD for all-day tasks or YYYY-MM-DDTHH:MM:SS for specific times.

Reminders: List of RFC 5545 triggers:

• TRIGGER:PT0S - At start time
• TRIGGER:P0DT1H0M0S - 1 hour before
• TRIGGER:P1DT0H0M0S - 1 day before

Priority levels: 0 (none), 1 (low), 3 (medium), 5 (high)

Match modes: When searching by title:

• exact - Title must match exactly (case-insensitive)
• partial - Title contains search term (default)
• fuzzy - Allows typos using Levenshtein distance

V2 API Tools (Optional)

These tools require V2 API credentials (TICKTICK_USERNAME and TICKTICK_PASSWORD):

Tool	Description
list_tags	List all tags in your account
add_tag	Add a tag to a task
remove_tag	Remove a tag from a task
search_tasks	Search tasks by title or content
sort_completed_tasks	Sort completed tasks alphabetically by completedTime

Enhanced list_tasks with V2:

• status="completed" - List completed tasks (V2 required)
• project_name="Inbox" - Access the Inbox project (V2 required)

Filtering Tasks

The list_tasks tool supports advanced filtering with combinable parameters:

Priority filter (priority):

• high - Priority 5 tasks
• medium - Priority 3 tasks
• low - Priority 1 tasks
• none - Priority 0 tasks (no priority set)

Due date filter (due):

• today - Tasks due today
• tomorrow - Tasks due tomorrow
• this_week - Tasks due within the next 7 days
• overdue - Tasks past their due date
• upcoming - Tasks with any future due date

Status filter (status):

• active - Active/incomplete tasks (default)
• completed - Completed tasks only
• all - All tasks regardless of status

Examples:

# High priority tasks due today
list_tasks(priority="high", due="today")

# All overdue tasks
list_tasks(due="overdue")

# Completed tasks in a specific project
list_tasks(project_name="Work", status="completed")

# Medium priority tasks due this week
list_tasks(priority="medium", due="this_week")

V2 API Features

The following features require V2 API credentials (optional):

• ✅ Inbox project access (list_tasks(project_name="Inbox"))
• ✅ Tag management (list_tags, add_tag, remove_tag)
• ✅ Listing completed tasks (list_tasks(status="completed"))
• ✅ Search tasks (search_tasks)
• ✅ Sort completed tasks alphabetically (sort_completed_tasks)

Without V2 credentials: All V1 features work normally. V2 features return helpful messages explaining how to enable them.

Migrating from cronjob-ticktick: The sort_completed_tasks tool replaces the standalone cronjob-ticktick project for sorting completed tasks alphabetically.

Setup

Option 1: Local Installation

1. Credentials: Create a .env file based on .env.example. You need your TickTick API credentials from the TickTick Developer Center.

2. Installation:

   uv pip install -e .
   

3. First-time OAuth Authentication: Run the server once locally to complete OAuth authentication. This will create a .token-oauth file.

4. Usage with Claude/Gemini: Add this to your MCP config:

   {
     "mcpServers": {
       "ticktick": {
         "command": "uv",
         "args": ["run", "--path", "/path/to/this/dir", "ticktick-mcp"]
       }
     }
   }
   

Option 2: Docker Deployment

Deploy the MCP server on your own infrastructure (VPS, home server) for remote access.

Prerequisites

• Docker and Docker Compose installed
• TickTick API credentials from Developer Center
• Completed OAuth authentication (.token-oauth file)

Quick Start

1. Create environment file:

   cp .env.example .env
   # Edit .env with your credentials
   

2. Build and start:

   docker-compose up -d
   

3. Verify health:

   curl http://localhost:8080/health
   # Expected: {"status": "ok"}
   

Environment Variables

Variable	Required	Description
TICKTICK_CLIENT_ID	Yes	OAuth2 client ID from TickTick Developer Center
TICKTICK_CLIENT_SECRET	Yes	OAuth2 client secret
TOKEN_CACHE_PATH	No	Path to OAuth token file (default: /app/data/.token-oauth)
HEALTH_PORT	No	Port for health check endpoint (default: 8080)
TICKTICK_USERNAME	No	Email for V2 API (enables tags, search, completed tasks, Inbox)
TICKTICK_PASSWORD	No	Password for V2 API (required with username)

OAuth Token Setup

The OAuth token must be generated locally first:

1. Run the server locally once to complete OAuth flow

2. Copy the generated .token-oauth file to your Docker volume:

   docker cp .token-oauth ticktick-mcp:/app/data/.token-oauth
   

   Or mount it directly in docker-compose.yml:

   volumes:
     - ./.token-oauth:/app/data/.token-oauth:ro
   

Docker Compose Configuration

The default docker-compose.yml includes:

• Health checks: Automatic container health monitoring
• Volume persistence: OAuth tokens survive container restarts
• Configurable ports: Change via HEALTH_PORT environment variable
• Restart policy: Container auto-restarts unless manually stopped

Custom Port

To use a different health check port:

HEALTH_PORT=9090 docker-compose up -d

Or in your .env file:

HEALTH_PORT=9090

Troubleshooting

"No OAuth token found"

The OAuth token file is missing or invalid:

1. Complete OAuth authentication locally first
2. Ensure the token file is accessible in the container
3. Check TOKEN_CACHE_PATH environment variable

Health check failing

1. Verify the container is running: docker ps
2. Check container logs: docker logs ticktick-mcp
3. Ensure port 8080 is not blocked by firewall

Container not starting

1. Check Docker logs: docker-compose logs
2. Verify environment variables are set correctly
3. Ensure credentials are valid

Development

Running Tests

uv pip install -e ".[dev]"
uv run pytest tests/ -v

Code Coverage

uv run pytest --cov=ticktick_mcp_py --cov-report=html

License

MIT