# partymola/ticktick-mcp [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/partymola/ticktick-mcp  
**GitHub Stars:** 1  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/partymola-ticktick-mcp

## Description
MCP server for TickTick task management: create, update, complete, move, and filter tasks with field-preserving updates and completion tracking.

## Tools
Capabilities this server exposes over MCP:

- **ticktick_create_task** — Create a task, preserving date/reminder/priority/timezone fields; warns if no due date is set (no reminder would fire)
- **ticktick_update_task** — Update a task by overlaying only the fields you set onto the current server object (omitted fields are never wiped)
- **ticktick_complete_task** — Mark a task complete and re-verify; distinguishes a recurring task rolling forward from a normal completion
- **ticktick_delete_tasks** — Delete one or more tasks by ID
- **ticktick_move_task** — Move a task into a different project
- **ticktick_make_subtask** — Nest one task as a subtask of another in the same project
- **ticktick_get_tasks_from_project** — List every open task in a project (compact or full)
- **ticktick_filter_tasks** — Find tasks by any mix of project, priority, tag, status, and due/completion-date window
- **ticktick_get_by_id** — Look up any task, project, or tag by its full ID
- **ticktick_get_all** — Dump all projects or all tags from local state
- **ticktick_sync** — Force an immediate refresh of local state from the server
- **ticktick_get_unprocessed_completions** — List recently completed tasks in a project not yet marked processed
- **ticktick_mark_completion_processed** — Record that a completed task has been reviewed, excluding it from future checks
- **ticktick_convert_datetime_to_ticktick_format** — Convert an ISO 8601 datetime + IANA timezone to TickTick's wire format

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "ticktick-mcp": {
    "command": "npx",
    "args": ["-y","partymola-ticktick-mcp"],
    "env": {
      "TICKTICK_CLIENT_ID": "",
      "TICKTICK_CLIENT_SECRET": "",
      "TICKTICK_REDIRECT_URI": "",
      "TICKTICK_USERNAME": "",
      "TICKTICK_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `TICKTICK_CLIENT_ID`, `TICKTICK_CLIENT_SECRET`, `TICKTICK_REDIRECT_URI`, `TICKTICK_USERNAME`, `TICKTICK_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What partymola/ticktick-mcp MCP server does

The partymola/ticktick-mcp MCP server connects MCP clients to a TickTick account for task management. It supports the main task lifecycle: creating, updating, completing, deleting, moving, and nesting tasks. It can also retrieve projects and tags, inspect individual entities by full ID, filter tasks across several fields, and force a refresh from TickTick.

The server includes completion-review workflows in addition to ordinary task operations. Agents can list recently completed tasks in a project, then mark each completion as processed so later checks exclude it. A datetime conversion tool accepts an ISO 8601 value and IANA timezone and produces TickTick's wire format.

## How it works

partymola/ticktick-mcp MCP server uses TickTick's unofficial v2 API through the ticktick-py library. It is a local stdio MCP server intended for Claude Code and other MCP clients. Read operations can re-sync remote state, allowing changes made in the TickTick application or on another device to appear without restarting the server.

Task updates are implemented as overlays: the server retrieves the current task and changes only the fields supplied by the caller. Omitted values are therefore not cleared accidentally. Operations that create or update tasks read the result back and report verification warnings if the returned data differs from the requested values. Date-setting calls validate the weekday to catch date mistakes before submission. Completing a recurring task is distinguished from completing a normal task because recurring tasks may roll forward.

## Setup and configuration

The project requires Python 3.13 or newer and recommends uv. Installation is performed from the repository with `git clone`, followed by `uv sync`; `pip install .` is also supported. The resulting console script is `.venv/bin/ticktick-mcp` on POSIX systems, with a Windows equivalent under `.venv\\Scripts`.

Authentication requires a registered TickTick application and an account. Configure `TICKTICK_CLIENT_ID`, `TICKTICK_CLIENT_SECRET`, `TICKTICK_REDIRECT_URI`, `TICKTICK_USERNAME`, and `TICKTICK_PASSWORD` in the server's `.env` file, or provide the `TICKTICK_*` values through the environment. The documented redirect URI is `http://localhost:8080/redirect`.

Run `.venv/bin/ticktick-mcp auth` in a terminal before registering the MCP server. This opens a browser-based authorization flow and caches the OAuth token. TickTick does not issue a refresh token, so authorization must be repeated when that token expires. The username and password session is established lazily on the first tool call and cached separately. The server can locate its dotenv directory through the `--dotenv-dir` argument, `TICKTICK_MCP_DOTENV_DIR`, or the default `~/.config/ticktick-mcp/` path.

## Tools and capabilities

partymola/ticktick-mcp MCP server provides tools for:

- Creating tasks with date, reminder, priority, and timezone fields.
- Updating tasks without wiping unspecified fields.
- Completing, deleting, moving, and nesting tasks.
- Listing open project tasks in compact or full form.
- Filtering by project, priority, tag, status, and due or completion date ranges.
- Looking up tasks, projects, or tags by full ID.
- Dumping projects or tags from local state and forcing synchronization.
- Tracking unprocessed completions and marking them reviewed.

Listings default to compact results to help keep large project responses within MCP result-size limits.

## Limitations and notes

The server is unofficial and is not affiliated with TickTick Ltd. It depends on TickTick's unofficial v2 API rather than the official Open API because its workflows require capabilities such as tags, completed-task listings, and cross-project task access. Changes to that unofficial API could affect operation.

Credentials are stored locally in the configured `.env` and token files and are sent to TickTick. The documented setup stores the account password in plain text, so file permissions should be tightened manually on systems where that matters. OAuth authorization must be completed outside the MCP process; attempting it through a stdio tool call can block because the authorization prompt reads standard input. Docker users must authorize on a host with a browser and mount the authorized configuration directory into the container.

_Full upstream README: https://allmcps.com/mcp/partymola-ticktick-mcp/readme_