karbassi/mcp-ticktick

8 stars 0 forks Quality 64 Trend 24

A Model Context Protocol server that gives LLMs full access to TickTick. Tasks, projects, habits, focus timers, tags, filters, calendar — all of it.

Overview

A Model Context Protocol server that gives LLMs full access to TickTick. Tasks, projects, habits, focus timers, tags, filters, calendar — all of it. Then add it to your AI client of choice: Add to ~/Library/Application Support/Claude/claude_desktop_config.json: Then set the environment variables in your shell. Add to ~/.codeium/windsurf/mcp_config.json: "Add a task to my Shopping list due tomorrow" "Check in my meditation habit for today" "Show me what I focused on this week" "Move all tasks tagged #backlog to the Archive project" Plus 4 read-only : ticktick://profile · ticktick://settings · ticktick://projects · ticktick://tags By default every client starts its own stdio process. To run one long-lived server that many clients share:

README

Quick Start

pip install mcp-ticktick

Then add it to your AI client of choice:

What Can It Do?

“Add a task to my Shopping list due tomorrow”
“Check in my meditation habit for today”
“Show me what I focused on this week”
“Move all tasks tagged #backlog to the Archive project”

Domain	Tools	Highlights
Tasks	10	Create, edit, complete, delete, move, subtasks, trash
Projects	5	CRUD with fuzzy name matching
Tags	6	Create, rename, merge, hierarchies
Folders	4	Group projects into folders
Habits	8	Track, check in, streaks, sections
Filters	4	Saved custom filters
Focus	5	Pomodoro records, stats, session history
Calendar	3	Connected calendars and events

Plus 4 read-only resources: ticktick://profile · ticktick://settings · ticktick://projects · ticktick://tags

Shared HTTP server

By default every client starts its own stdio process. To run one long-lived server that many clients share:

TICKTICK_MCP_TRANSPORT=http TICKTICK_MCP_PORT=8502 mcp-ticktick

{
  "mcpServers": {
    "ticktick": { "type": "http", "url": "http://127.0.0.1:8502/mcp" }
  }
}

The endpoint has no authentication: anything that can connect to it can use every tool with your TickTick credentials, including deleting projects. So:

The server only binds to loopback (TICKTICK_MCP_HOST must be 127.0.0.1, localhost, or ::1). Any local process can still connect, so only use HTTP mode on a machine where every local user and process is trusted with your TickTick account.
It always turns on FastMCP’s Host/Origin protection, which FastMCP leaves off by default. That check only stops DNS-rebinding attacks from web pages. It does not authenticate anyone.
To reach it from another machine, put it behind a reverse proxy that controls who can connect: a bearer token, mTLS, an IP allowlist on a private network, or similar. Then add the proxy’s hostname to FASTMCP_HTTP_ALLOWED_HOSTS, e.g. FASTMCP_HTTP_ALLOWED_HOSTS='["mcp.example.com"]'. If a browser-based client will call it, also add that client’s origin to FASTMCP_HTTP_ALLOWED_ORIGINS, e.g. '["https://mcp.example.com"]'. Never expose the port or the proxy publicly without access control.

Authentication

You need a TickTick OAuth app (free to create).

Variable	Required	Description
`TICKTICK_ACCESS_TOKEN`	Yes	OAuth access token
`TICKTICK_CLIENT_ID`	No	OAuth client ID (for token refresh)
`TICKTICK_CLIENT_SECRET`	No	OAuth client secret (for token refresh)
`TICKTICK_REFRESH_TOKEN`	No	OAuth refresh token
`TICKTICK_V2_SESSION_TOKEN`	No	Browser `t` cookie for v2 features

v1 vs v2: The access token covers tasks and projects. For tags, folders, filters, habits, focus, and calendar you also need a v2 session token — grab the t cookie from your browser while logged into ticktick.com.

Development

git clone https://github.com/karbassi/mcp-ticktick.git
cd ticktick-mcp
uv sync --all-extras
uv run ruff check src/ tests/
uv run pytest

License

MIT

View the full README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "ticktick": {
      "command": "mcp-ticktick",
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your-access-token",
        "TICKTICK_V2_SESSION_TOKEN": "your-session-cookie"
      }
    }
  }
}