TickTick MCP Server

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.

1. Installation:

   uv pip install -e .

1. First-time OAuth Authentication:

Run the server once locally to complete OAuth authentication. This will create a .token-oauth file.

1. Usage with Claude/Gemini:

Add this to your MCP config: ``json { "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

1. Build and start:

   docker-compose up -d

1. 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: ```yaml 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