tick-mcp 0.2.0

MCP server for TickTick — task and notes access via Model Context Protocol.

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

Category	Tools
Tasks	create_task · update_task · complete_task · reopen_task · delete_task · get_task_detail · get_project_tasks · get_inbox · get_all_tasks
Batch	batch_create_tasks · batch_update_tasks · batch_delete_tasks · move_tasks
Projects	create_project · update_project · delete_project · get_project_detail · list_projects
Query / Search	workspace_map · query_projects · query_folders · query_tasks · query_notes · query_agenda · query_task_history · list_query_presets · save_query_preset · run_query_preset · delete_query_preset
Views	tasks_of_today · events_of_today · week_agenda · week_overview · upcoming_tasks · overdue_tasks · stale_tasks · priority_dashboard
Verified Actions	create_subtask · verified_create_project · verified_set_subtask_parent · verified_move_tasks · verified_batch_move · verified_assign_project_folder
Tags	create_tag · update_tag · rename_tag · merge_tags · delete_tag · list_tags
Habits	create_habit · update_habit · delete_habit · list_habits · habit_checkin · get_habit_records · list_habit_sections
Kanban	list_columns · manage_columns
Folders	list_project_folders · manage_project_folders
Focus	get_focus_stats
History	get_completed_tasks · get_deleted_tasks
Subtasks	set_subtask_parent
Sync / Stats	full_sync · get_user_status · get_productivity_stats
Utilities	ticktick_guide · check_v2_availability · build_recurrence_rule · build_reminder

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/
├── admin/
│   ├── service.py       # shared admin/runtime status, token, session, and log logic
│   ├── cli.py           # tick-admin Typer surface
│   └── telegram.py      # Telegram command dispatcher over the shared admin service
├── 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
├── http_app.py          # health/admin HTTP wrapper around the MCP streamable transport
├── main.py              # CLI entrypoint
└── .env.example         # single canonical env template for local and deploy usage

Operator Takeover

Use this sequence when another operator or maintainer takes over the project:

1. Read README.md
   -> architecture, transports, deployment, admin model

2. Read TODO.md
   -> current follow-up work

3. Read CHANGELOG.md
   -> what changed recently and why

Then run the minimum smoke checks:

uv run python -m py_compile $(find src -name '*.py' -print)
uv run --group dev python -m pytest tests -q
curl -fsS https://tick.kpihx-labs.com/health
curl -fsS https://tick.kpihx-labs.com/admin/status

Installation

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

# or via pip
pip install tick-mcp

This provides two commands:

Command	Description
tick-mcp	Start the MCP server (stdio by default, HTTP via serve-http)
tick-admin	CLI admin surface — status, help, logs, and credential actions

Quick operator capability summary:

tick-admin help

Configuration

1. Environment variables

Copy the example file and fill in your tokens:

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

Variable	Required	Description
TICKTICK_API_TOKEN	Yes	V1 Open API bearer token (PAT or OAuth2)
TICKTICK_SESSION_TOKEN	No	V2 session cookie for extended features
TICKTICK_USERNAME	No	TickTick login email, used by non-interactive session refresh flows
TICKTICK_PASSWORD	No	TickTick password, used by non-interactive session refresh flows
TICK_MCP_ADMIN_ENV_FILE	No	Persistent admin env file path. In Docker, use /data/tick-admin.env.
TELEGRAM_TICK_HOMELAB_TOKEN	No	Telegram bot token for the homelab admin bridge
TELEGRAM_CHAT_IDS	No	Comma-separated Telegram chat IDs allowed to issue admin commands

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, user-agent, and HTTP transport defaults are all externalised there.

3. Dual transport model

The same server surface now supports two transport modes:

# Local fallback (current default)
tick-mcp serve

# Homelab / remote MCP transport
tick-mcp serve-http

HTTP defaults:

• MCP endpoint: /mcp
• Health endpoint: /health
• Admin status endpoint: /admin/status
• Admin help endpoint: /admin/help
• Admin log endpoint: /admin/logs?lines=40
• Primary URL: https://tick.kpihx-labs.com
• Fallback URL: https://tick.homelab
• Telegram admin: auto-started inside the HTTP service when both Telegram env vars are configured
• Auth observability: /health and /admin/status expose presence booleans for API token, session token, username, and password without leaking values

Operational intent:

remote HTTP on the homelab
-> preferred transport for agents and automations

local stdio
-> immediate fallback if the remote service is unavailable

Transport map

Local agent
-> zsh -l -c "tick-mcp serve"
-> stdio MCP

Remote agent / automation
-> https://tick.kpihx-labs.com/mcp
-> same MCP tool surface over HTTP

Operator
-> tick-admin ...
-> or Telegram admin commands
-> both call the same shared admin service

4. Docker / Homelab deployment

Deployment artifacts are bundled in the repo:

• Dockerfile
• deploy/docker-compose.yml
• deploy/docker-compose.override.example.yml
• src/tick_mcp/.env.example
• .dockerignore
• .gitlab-ci.yml

Typical local dry-run:

cd deploy
cp .env.example .env
docker compose config -q
docker compose up --build

Typical SSH-side admin once deployed on the server:

cd deploy
docker compose exec -T tick-mcp tick-admin status
docker compose logs --tail=100 tick-mcp
curl -fsS http://127.0.0.1:8091/health

Persistent admin state inside Docker:

/data/tick-admin.env
-> mounted as a named Docker volume
-> used by tick-admin and the Telegram bridge
-> survives container restarts and rebuilds

Telegram commands currently supported:

/start
/help
/status
/health
/urls
/logs [lines]
/api_set <token> [expires_at_iso]
/api_unset
/session_set <token> [ttl_days]
/session_unset
/session_refresh
/user_set <email>
/user_unset
/pass_set <password>
/pass_unset
/restart

Notes:

• /session_refresh resolves credentials in this order: CLI/command override, admin .env file, current process environment, then login shell (zsh -l). Interactive prompting only exists on the CLI surface.
• If TickTick requires MFA code entry or an email-link approval, Telegram will refuse and tell you to use tick-admin session refresh over SSH.
• /restart exits the live HTTP process; Docker restarts it automatically because the service runs with restart: unless-stopped.
• /status reports every admin variable separately, with its own source (admin .env file, process environment, login shell (zsh -l), or missing).

The same capability summary is available through:

• CLI: tick-admin help
• HTTP: GET /admin/help
• Telegram: /help

Shared admin help

The admin interface is defined once in the shared admin service and then rendered for each surface:

• CLI: tick-admin help
• HTTP: GET /admin/help
• Telegram: /help

Use those live help entrypoints as the source of truth for the exact commands, arguments, and route names. The README should explain the model and operator intent, not duplicate the full generated help verbatim.

Real-world admin validation checklist

After a deploy, validate these paths:

# inside the server / container host
docker exec tick-mcp tick-admin status

# HTTP operator surface
curl -fsS https://tick.kpihx-labs.com/health
curl -fsS https://tick.kpihx-labs.com/admin/status
curl -fsS https://tick.kpihx-labs.com/admin/help
curl -fsS "https://tick.kpihx-labs.com/admin/logs?lines=20"

# Telegram bridge
# simulate or trigger /help, /status, /logs, /session_refresh, and /restart

5. GitLab deployment prerequisites

For a push on main to deploy successfully, the GitLab project must have:

• a runner tagged homelab
• the CI variables:
  • TICKTICK_API_TOKEN
  • TICKTICK_SESSION_TOKEN
  • TICKTICK_USERNAME
  • TICKTICK_PASSWORD
  • TELEGRAM_TICK_HOMELAB_TOKEN
  • TELEGRAM_CHAT_IDS

Pipeline behavior:

validate
-> unit tests + import smoke tests

deploy_homelab
-> writes deploy/.env
-> docker compose up -d --build
-> probes /health locally on the docker host

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.

For clients that support remote MCP over HTTP, prefer the homelab endpoint first and keep the current stdio setup as a fallback profile:

Primary : https://tick.kpihx-labs.com/mcp
Fallback: tick-mcp serve

Development

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

# Unit tests (170 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

• 170 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