tick-mcp

MCP server for TickTick — manage tasks, projects, habits, tags, focus stats, and more through the Model Context Protocol.

71 tools exposed over MCP, covering both the official TickTick Open API (V1) and the unofficial web API (V2) for features not yet available publicly.

Features

Query / Search highlights

• Structured task filtering — folders, projects, tags, parent/subtask shape, reminders, recurrence, checklist presence, and priorities.

• Time-aware agenda access — query by date range, datetime range, and HH:MM time windows without forcing a full sync first.

• Grep-like matching — substring search, any / all / phrase keyword modes, regex, and exclusion regex across chosen fields.

• Targeted note search — notes are fetched only from NOTE projects in scope instead of materializing the whole workspace.

• Workspace navigation — folder/project map with optional active task counts to inspect the account structure before acting.

• Ready-made operational views — day view, week window, upcoming due tasks, overdue/stale detection, and priority summaries built on the same filter engine.

• Saved query presets — persist reusable task/note/agenda/history/week-overview queries and execute them later without rebuilding the filter set.

Verified workflow helpers

• Subtask-safe creation — create_subtask creates the child, links it, then verifies parentId and childIds.

• Move verification — verified_move_tasks re-reads destination projects and confirms every moved task is actually there.

• Folder assignment verification — verified_assign_project_folder verifies the persisted groupId through V2 sync, not through the misleading V1 response.

Intent-first discovery

ticktick_guide() supports both technical categories and real user goals.

• Category-oriented:

  • ticktick_guide(category="tasks")

• Intent-oriented:

  • ticktick_guide(intent="know_what_to_do_today")

  • ticktick_guide(intent="plan_the_week")

  • ticktick_guide(intent="find_a_note")

  • ticktick_guide(intent="reorganize_projects")

  • ticktick_guide(intent="clean_up_tasks")

Package Layout

src/tick_mcp/
├── mcp_api/
│   ├── core.py          # shared FastMCP instance, catalog, helpers
│   ├── utilities.py     # discovery + helper tools
│   ├── projects.py      # project CRUD tools
│   ├── tasks_read.py    # inbox / project / task reads
│   ├── tasks_write.py   # task mutation tools
│   ├── tasks_batch.py   # batch + structural task operations
│   ├── read.py          # high-level query/search, views, and saved presets
│   ├── verified.py      # safe wrappers with read-back verification + rollback hints
│   ├── folders.py       # folders + kanban columns
│   ├── tags.py          # tag tools
│   ├── habits.py        # habit tools
│   ├── history.py       # completed / deleted history
│   └── stats.py         # focus and user/productivity stats
├── services/
│   └── query.py         # reusable filtering, range and grep-like planning
├── client_api/
│   ├── transport.py     # auth, sessions, low-level V1/V2 HTTP helpers
│   ├── projects.py      # projects, folders, columns, tags
│   ├── tasks.py         # tasks, sync, batch, history
│   ├── habits.py        # habits and check-ins
│   └── stats.py         # focus and user/productivity stats
├── client.py            # stable public facade over client_api/*
├── models.py            # pydantic contracts
├── server.py            # stable public import surface for the MCP server
└── main.py              # CLI entrypoint

Installation

# recommended — installs as a standalone tool
uv tool install tick-mcp

# or via pip
pip install tick-mcp

This provides two commands:

Configuration

1. Environment variables

Copy the example file and fill in your tokens:

cp src/tick_mcp/.env.example src/tick_mcp/.env

Getting a V1 token (simplest):

1. Open TickTick → Settings → Integrations → API

2. Copy the displayed Personal Access Token

Getting a V2 session token:

1. Log in to ticktick.com in your browser

2. DevTools → Application → Cookies → copy the t cookie value

Or use the CLI to auto-login:

tick-admin session refresh

2. Server config

Runtime settings live in src/tick_mcp/config.yaml — API endpoints, timeouts, and user-agent are all externalised there.

MCP Client Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "ticktick": {
      "command": "tick-mcp",
      "env": {
        "TICKTICK_API_TOKEN": "your-v1-token",
        "TICKTICK_SESSION_TOKEN": "your-v2-token"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "tick-mcp",
      "env": {
        "TICKTICK_API_TOKEN": "your-v1-token",
        "TICKTICK_SESSION_TOKEN": "your-v2-token"
      }
    }
  }
}

Other MCP clients

Any client that supports the stdio transport can launch tick-mcp as a subprocess.

Development

# Clone & install dev deps
git clone https://github.com/kpihx/tick-mcp.git
cd tick-mcp
uv sync --group dev

# Unit tests (155 selected unit tests, no network)
uv run pytest

# Live tests against real TickTick API (requires tokens in .env)
uv run pytest -m live

Test suite

• 155 selected unit tests — pure logic, mocked HTTP, zero network

• 12 live integration scripts — 508 assertions against the real TickTick API

License

MIT © 2025 Ivann KAMDEM