ticktick-mcp
Provides tools for managing TickTick tasks, projects, tags, and comments, including listing, filtering, searching, creating, updating, completing, deleting, and moving tasks, plus managing projects and comments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ticktick-mcp add "Send quarterly report" to Work, due Friday, high priority"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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,
$ticktickcommand.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 loginonce. It opens the browser, receives the localhost callback, and stores the token in~/.config/ticktick-connector/oauth.jsonwith 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-connectorUse it with Codex
Log in once:
npx -y github:DracieVajko/ticktick-connector loginThen 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:
npxArguments:
-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 --helpToken fallback
If your environment cannot open a browser, you can still use a TickTick personal API token:
export TICKTICK_API_TOKEN=your_tokenOr 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 |
| The arguments failed validation (bad date, unknown field, out-of-range value). |
| An environment override is unusable, for example a plain-http |
| A destructive tool was called without |
| The tool name does not exist. |
| TickTick rejected the authorization (HTTP 401/403). |
| No OAuth token or personal token is configured. |
| The saved authorization expired and there is no refresh token. |
| The browser sign-in failed (state mismatch, cancelled, or missing code). |
| The OAuth callback port is busy. |
| The browser sign-in was not completed in time. |
| The token file could not be read or removed. |
| The OAuth code or refresh-token call failed. |
| Any other non-2xx answer from the API. |
| The requested task does not exist. |
| An unexpected failure inside the connector. |
| The request never reached TickTick. |
| The request exceeded |
| Cindy truncated the response. |
Environment
Variable | Purpose |
| Personal API token, used instead of OAuth. |
| File containing a personal API token. |
| OAuth token storage (default |
| API base override. Must be |
| Request timeout, default |
| OAuth callback port, default |
| OAuth client id override. |
| OAuth authorize URL override. |
| OAuth token URL override. |
| Do not open a browser during |
| Log stack traces to stderr. |
Security notes
OAuth tokens are stored in
~/.config/ticktick-connector/oauth.jsonwith mode0600; 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.comunless you overrideTICKTICK_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 testThe 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 toolscomplete_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_projectADestructive
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_taskADestructive
Permanently delete a TickTick task. Requires confirm:true; ask the user first.
Inputs: taskId (required), projectId (required), confirm.
filter_tasksARead-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_projectARead-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_taskARead-only
Get one TickTick task by projectId and taskId, including its checklist and recurrence.
Inputs: taskId (required), projectId (required).
list_projectsARead-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_tasksARead-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_commentsADestructive
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_tasksARead-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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage TickTick tasks and projects through OAuth2 authentication, supporting task creation, updates, completion, project management, and smart daily scheduling based on priorities and due dates.55MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with TickTick task management system through MCP, allowing users to view, create, update, complete, and delete tasks and projects via natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage tasks and projects in TickTick through the TickTick Open API, supporting CRUD operations on tasks and projects.9 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage TickTick/Dida365 tasks, projects, and tags through the MCP protocol, with features for GTD-based task organization and OAuth authentication.10ISC