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

Related MCP server: TickTick MCP Server

Available MCP Tools

Task Management

Subtask Management

Project Management

GTD (Getting Things Done) Tools

Dedicated tools for GTD productivity workflows:

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):

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

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