TickTick任务管理MCP服务

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
• Search across all lists and the Inbox (title, notes, checklist items), V1 only
• V2 API features (optional): Completed tasks, Inbox listing, and tags

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"))
• ✅ Sort completed tasks alphabetically (sort_completed_tasks)

Without V2 credentials: All V1 features work normally, including search_tasks (open tasks in all lists and the Inbox; completed tasks are not searched). V2 features return a message explaining how to enable them, or that the sign-in was rejected if credentials are set.

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. TickTick issues no refresh_token, so this step has to be repeated from a real terminal whenever the cached token expires -- the MCP server itself will not (and cannot) do this interactively, since its stdin/stdout are reserved for the MCP protocol, not a human typing into a browser-login prompt.

1. Run uv run ticktick-mcp-reauth locally to complete the OAuth flow (opens a browser; paste the redirected URL back when prompted)

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 valid OAuth token at ..."

The OAuth token file is missing or expired (TickTick issues no refresh_token, so this cannot self-heal):

1. Run uv run ticktick-mcp-reauth locally to renew it
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