Skip to main content
Glama

TickTick connector for Cindy, Claude, Codex and other MCP clients

One TickTick implementation, two ways to use it. Cindy is the primary target; the same source also ships a portable MCP server for every other harness.

  • Cindy plugin — native tools, OAuth token stored in Cindy’s encrypted vault, $ticktick command.

  • MCP server — a dependency-free stdio server for Claude Code, Codex, Claude Desktop, Cursor and any other MCP client, with its own browser OAuth login.

It manages tasks, projects, tags and comments in TickTick. Habits, focus sessions and countdowns are intentionally out of scope for v1.

What it can do

Area

Actions

Projects

list (including Inbox), get, create, update, delete

Tasks

list, filter, search, get, create, update, complete, complete in bulk, delete, move

Tags

list, create

Comments

list, add, delete

Account

read time zone preferences

Dates accept YYYY-MM-DD or ISO 8601 and are normalized to TickTick’s yyyy-MM-dd'T'HH:mm:ssZ format. Priorities accept none / low / medium / high or 0 / 1 / 3 / 5.

Related MCP server: TickTick MCP Server

Authentication

No manually copied API token is needed.

  • Cindy plugin: click Connect TickTick and sign in through the browser. Cindy stores and refreshes the OAuth token in its encrypted vault.

  • MCP server: run ticktick-mcp login once. It opens the browser, receives the localhost callback, and stores the token in ~/.config/ticktick-connector/oauth.json with owner-only permissions.

Both use TickTick’s OAuth PKCE flow with the tasks:read and tasks:write scopes. The OAuth callback is http://127.0.0.1:53682/callback.

Use it in Cindy

Install the plugin from the Cindy marketplace, or import the .cindy package. Then click Connect TickTick in the plugin settings and approve access in the browser.

$ticktick show my open tasks
$ticktick add "Send the quarterly report" to Work, due Friday, high priority
$ticktick what is due this week?

Use it with Claude Code

# One-time browser login
npx -y github:DracieVajko/ticktick-connector login

# Register the MCP server
claude mcp add ticktick -- npx -y github:DracieVajko/ticktick-connector

Use it with Codex

Log in once:

npx -y github:DracieVajko/ticktick-connector login

Then add this to ~/.codex/config.toml:

[mcp_servers.ticktick]
command = "npx"
args = ["-y", "github:DracieVajko/ticktick-connector"]

Use it with Claude Desktop

Log in once, then edit claude_desktop_config.json:

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "github:DracieVajko/ticktick-connector"]
    }
  }
}

Use it with Cursor or another MCP client

Use stdio with:

  • Command: npx

  • Arguments: -y github:DracieVajko/ticktick-connector

Run the login command once before starting the client. The server has no runtime dependencies and requires Node.js 18 or newer.

Commands

ticktick-mcp login     # browser OAuth login
ticktick-mcp logout    # remove the saved OAuth token
ticktick-mcp --check   # verify the connection
ticktick-mcp --version
ticktick-mcp --help

Token fallback

If your environment cannot open a browser, you can still use a TickTick personal API token:

export TICKTICK_API_TOKEN=your_token

Or put the token in TICKTICK_TOKEN_FILE, ~/.config/ticktick-connector/token, or ~/.ticktick-connector/token. The environment variable takes precedence over the OAuth file.

Tools

list_projects, get_project, create_project, update_project, delete_project, list_tasks, filter_tasks, search_tasks, get_task, create_task, update_task, complete_task, delete_task, move_tasks, manage_tags, manage_comments.

list_projects includes a synthetic inbox project. Use projectId: "inbox" to create an Inbox task.

Destructive tools require confirm: true. Tool descriptions tell the model to ask first.

Every read tool returns a projection of the fields the user needs, so a raw TickTick payload (with etag, focusSummaries and vendor extras) never reaches the model.

Arguments that a tool does not declare are rejected instead of being dropped, so a typo such as dueDAte fails loudly.

Error codes

Failures come back as a TickTickError with one of these codes:

Code

Meaning

INVALID_ARGUMENTS

The arguments failed validation (bad date, unknown field, out-of-range value).

INVALID_CONFIGURATION

An environment override is unusable, for example a plain-http TICKTICK_API_BASE.

CONFIRM_REQUIRED

A destructive tool was called without confirm: true.

UNKNOWN_TOOL

The tool name does not exist.

TICKTICK_AUTH

TickTick rejected the authorization (HTTP 401/403).

TICKTICK_TOKEN_MISSING

No OAuth token or personal token is configured.

TICKTICK_AUTH_EXPIRED

The saved authorization expired and there is no refresh token.

TICKTICK_OAUTH

The browser sign-in failed (state mismatch, cancelled, or missing code).

TICKTICK_OAUTH_LISTEN

The OAuth callback port is busy.

TICKTICK_OAUTH_TIMEOUT

The browser sign-in was not completed in time.

TICKTICK_TOKEN_STORE

The token file could not be read or removed.

TICKTICK_OAUTH_EXCHANGE

The OAuth code or refresh-token call failed.

TICKTICK_HTTP

Any other non-2xx answer from the API.

TICKTICK_NOT_FOUND

The requested task does not exist.

TICKTICK_CONNECTOR_ERROR

An unexpected failure inside the connector.

TICKTICK_NETWORK

The request never reached TickTick.

TICKTICK_TIMEOUT

The request exceeded TICKTICK_TIMEOUT_MS.

TICKTICK_RESPONSE_TOO_LARGE

Cindy truncated the response.

Environment

Variable

Purpose

TICKTICK_API_TOKEN

Personal API token, used instead of OAuth.

TICKTICK_TOKEN_FILE

File containing a personal API token.

TICKTICK_OAUTH_FILE

OAuth token storage (default ~/.config/ticktick-connector/oauth.json).

TICKTICK_API_BASE

API base override. Must be https, except on localhost.

TICKTICK_TIMEOUT_MS

Request timeout, default 30000.

TICKTICK_REDIRECT_PORT

OAuth callback port, default 53682; 0 picks a free port.

TICKTICK_OAUTH_CLIENT_ID

OAuth client id override.

TICKTICK_OAUTH_AUTHORIZE_URL

OAuth authorize URL override.

TICKTICK_OAUTH_TOKEN_URL

OAuth token URL override.

TICKTICK_NO_BROWSER

Do not open a browser during login.

TICKTICK_DEBUG

Log stack traces to stderr.

Security notes

  • OAuth tokens are stored in ~/.config/ticktick-connector/oauth.json with mode 0600; refresh tokens never leave your machine except to TickTick’s token endpoint.

  • The Cindy plugin never exposes the OAuth token to plugin JavaScript; Cindy injects it at request time.

  • The MCP server only sends the token to api.ticktick.com unless you override TICKTICK_API_BASE, and plain http is refused outside localhost.

  • This project is not affiliated with TickTick. TickTick and its logo are trademarks of their owner. The icon is the official app icon from TickTick’s website.

Development

npm install
npm run build     # regenerate cindy-plugin/ from src/: ghost.json, main.js, settings.js, settings.html
npm test

The entire plugin source lives in src/. cindy-plugin/ contains only what ships: files generated by the build, the shipped READMEs and the icon. The MCP server runs directly from src/mcp-server.mjs.

License

MIT. See LICENSE.

Available Tools

16 tools
complete_taskA

Mark one TickTick task completed, or complete up to 50 tasks in one project by passing taskIds. For taskIds, omit projectId to use the inbox.

Inputs: taskId, taskIds, projectId.

create_projectB

Create a TickTick project and return its new ID.

Inputs: name (required), kind, color, viewMode.

create_taskB

Create a TickTick task in a project. Dates accept YYYY-MM-DD or ISO 8601; priority accepts none/low/medium/high or 0/1/3/5.

Inputs: title (required), projectId (required), desc, tags, +11 more.

delete_projectA
Destructive

Permanently delete a TickTick project. Requires confirm:true; ask the user first. Prefer closing tasks or moving them when unsure.

Inputs: projectId (required), confirm.

delete_taskA
Destructive

Permanently delete a TickTick task. Requires confirm:true; ask the user first.

Inputs: taskId (required), projectId (required), confirm.

filter_tasksA
Read-only

Find TickTick tasks by project, date range, priority, tags or status. Use this for agendas and due-date queries; results are capped at 200.

Inputs: tags, limit, status, endDate, +3 more.

get_projectA
Read-only

Get one TickTick project. With includeTasks true (default) it also returns the project columns and its open tasks; with false, count, tasks and columns are null.

Inputs: projectId (required), includeTasks.

get_taskA
Read-only

Get one TickTick task by projectId and taskId, including its checklist and recurrence.

Inputs: taskId (required), projectId (required).

list_projectsA
Read-only

List TickTick projects, including the Inbox alias, with their IDs, names, colors and permissions. Use the returned projectId in task tools.

Inputs: limit, offset.

list_tasksA
Read-only

List TickTick tasks, optionally limited to one project or "inbox". Status can be open, completed or all; results are capped at 200.

Inputs: limit, status, projectId.

manage_commentsA
Destructive

List, add or delete comments on a TickTick task. Use action "list", "add" with content, or "delete" with commentId and confirm:true.

Inputs: action (required), taskId (required), projectId (required), confirm, +2 more.

manage_tagsA

List TickTick tags, or create one. Use action "list" to see tags, or action "create" with a name.

Inputs: action (required), name, label.

move_tasksC

Move up to 50 TickTick tasks from one project to another.

Inputs: taskIds (required), toProjectId (required), fromProjectId (required).

search_tasksA
Read-only

Search TickTick tasks by keyword, with optional project, tag, status and due-date filters. Results are capped at 200.

Inputs: keywords (required), tags, dueTo, limit, +3 more.

update_projectB

Rename or change the color, view or kind of an existing TickTick project.

Inputs: projectId (required), kind, name, color, +2 more.

update_taskA

Update fields on an existing TickTick task. Omitted fields stay unchanged. Use complete_task to mark it done or move_tasks to move it.

Inputs: taskId (required), projectId (required), desc, tags, +13 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation3/5

    Several task-retrieval tools overlap: list_tasks, filter_tasks, and search_tasks all return tasks and could be confused depending on whether the agent needs a simple list, date/priority filtering, or keyword search. Descriptions provide guidance, but the boundaries are not crisp enough to prevent occasional misselection.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: list_projects, get_project, create_task, update_task, complete_task, move_tasks, manage_tags, manage_comments, etc. The conventions are predictable and readable throughout.

    Tool Count4/5

    At 16 tools, the surface is slightly heavy but justified by distinct resource areas: projects, tasks, tags, comments, and bulk operations. Each tool has a plausible role, though the three task-query tools could potentially be consolidated.

    Completeness4/5

    Core lifecycle coverage is strong: full CRUD for projects and tasks, plus completion and bulk movement. Minor gaps remain around tag update/delete, comment editing, and checklist/subtask mutation, but these are workaroundable and not central to most workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers