# 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](https://developer.ticktick.com/manage).

2. **Installation:**
   ```bash
   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:
   ```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](https://developer.ticktick.com/manage)
- Completed OAuth authentication (`.token-oauth` file)

#### Quick Start

1. **Create environment file:**
   ```bash
   cp .env.example .env
   # Edit .env with your credentials
   ```

2. **Build and start:**
   ```bash
   docker-compose up -d
   ```

3. **Verify health:**
   ```bash
   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:
   ```bash
   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:

```bash
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

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

### Code Coverage

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

## License

MIT