io.github.partymola/ticktick-mcp

Mark a task as completed. Completing a task here also records it as processed, so it does not come back from ``ticktick_get_unprocessed_completions``. That queue is for completions made elsewhere, where a note may be waiting to be read. There is no need to call ``ticktick_mark_completion_processed`` afterwards. Args: task_id (str): The task's full ID. Returns: After a completion call, a JSON object carrying ``outcome``. ``completed``: the task is no longer open. It has usually left the active list, so no task object comes back; one that can still be read is returned at status=2. ``completed_recurring``: the next occurrence, at status=0, with ``next_occurrence_id``. ``uncertain``: a non-recurring task is still open, with ``_verification_warnings`` saying so. ``completion_recorded`` reports whether the local record was written. Present only when a non-recurring task completed; absent wherever nothing was recorded, which is every recurring completion and ``outcome: "uncertain"``. The task is complete either way. Missing task: ``{"status": "not_found", "error": "..."}``. Other failures: ``{"error": "...", "status": "error"}``. Limitations: - Once completed, the ``content`` field becomes immutable. Update content with resolution notes BEFORE calling this tool. - A recurring task's completion is never recorded, whatever the outcome: completing one files the completed instance under an id this tool never sees. That instance reaches the unprocessed queue. Do not mark the series id processed by hand instead; it is not the id the queue is showing. Example: ticktick_complete_task(task_id="60ca9dbc8f08516d9dd56324")

Convert an ISO 8601 datetime string into TickTick's storage format. TickTick uses ``YYYY-MM-DDTHH:MM:SS+0000`` (UTC offset, no colon). Args: datetime_iso_string (str): ISO 8601 datetime, e.g. ``"2026-04-13T20:45:00+01:00"``. Naive strings are accepted and interpreted in ``tz``. tz (str): IANA timezone name used for the UTC conversion, e.g. ``"Europe/London"`` or ``"America/Los_Angeles"``. Returns: On success: ``{"ticktick_format": "2026-04-13T19:45:00+0000"}``. On parse error: ``{"error": "Invalid datetime format...", "status": "error"}``. On any other conversion error: ``{"error": "Conversion failed: ...", "status": "error"}``. Agent Usage Guide: - Call this when you need to set ``startDate`` or ``dueDate`` on a task dict by hand. The ``ticktick_create_task`` and ``ticktick_update_task`` tools accept ISO strings directly and run this conversion internally. Example: ticktick_convert_datetime_to_ticktick_format( datetime_iso_string="2026-04-13T20:45:00+01:00", tz="Europe/London", )

Create a new task. Args: title (str): Task title. Required. project_id (str, optional): Project ID or name. Defaults to inbox. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. content (str, optional): Long-form content (markdown supported). desc (str, optional): Short description / checklist subtitle. all_day (bool, optional): True for all-day tasks. start_date (str, optional): ISO 8601 start datetime, e.g. ``"2026-04-13T09:00:00+01:00"``. due_date (str, optional): ISO 8601 due datetime. expected_day_of_week (str, optional): English weekday name. Required when ``due_date`` is set; mismatch returns an error. time_zone (str, optional): IANA timezone. Defaults to the system timezone for date conversion. reminders (list[str], optional): TickTick trigger strings, e.g. ``["TRIGGER:-PT30M"]``. repeat (str, optional): Recurrence rule (RFC 5545 RRULE). priority (int, optional): 0=None, 1=Low, 3=Medium, 5=High. sort_order (int, optional): Position within project. items (list[dict], optional): Subtask items. Returns: JSON object containing the created task. ``_verification_warnings`` carries everything worth knowing about what landed: a response that did not match what was sent, a due date that is missing and so will fire no reminder at all or all-day and so no timed one, a title character TickTick parses as a marker, and content longer than the compact preview. On failure: ``{"error": "...", "status": "error"}``. Limitations: - ``builder()`` in ``ticktick-py`` sometimes omits dates, reminders, priority and timezone; we re-populate them after the call. Agent Usage Guide: - Always pair ``due_date`` with ``expected_day_of_week``. - Pass a project name directly, or list ids with ticktick_get_all(sear…

Delete one or more tasks. Args: task_ids (str | list[str]): A single task ID, or a list of IDs. An empty list returns an error. project_id (str, optional): Used to construct a minimal delete payload when ``get_by_id`` cannot find the task locally (typical for completed tasks). Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. Returns: ``{"status": "success", "deleted_count": N, "tasks_deleted_ids": [...]}`` on success. Tasks that could not be matched at all are returned as ``status="not_found"`` with ``missing_ids`` / ``invalid_ids`` arrays. Partial success surfaces ``warnings``. Empty input: ``{"status": "error", "message": "No task IDs..."}``. Agent Usage Guide: - For tasks already completed in TickTick, supply ``project_id`` -- ``get_by_id`` does not see completed tasks. Example: ticktick_delete_tasks( task_ids=["abc123", "def456"], project_id="<your-project-id>", )

Return the tasks matching every supplied filter criterion. Supports any combination of project, priority, tag, status, and a date window applied to either the due date (open tasks) or the completion timestamp (completed tasks). Args: detail (str, optional): ``"compact"`` (default) or ``"full"``. Compact drops the heavy ``content``/``desc``/checklist ``items`` blobs and bulky sync metadata, keeping id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags plus a ``contentPreview`` (first ~200 chars of content) so keyword search still works. Full returns the raw task objects unchanged. To edit a task, call ``ticktick_update_task`` with its id and only the fields to change, plus ``projectId`` for a completed task. filter_criteria (dict | str): A criteria object, or a JSON string that decodes to one. No value below reaches the query unchecked, and **any key not on this list is an error** rather than something ignored, so a mistyped key fails loudly. Recognised keys: * ``status``: ``"uncompleted"`` (default) or ``"completed"``. When ``"completed"`` you should supply ``completion_start_date`` and/or ``completion_end_date``; without dates the result is an empty list. * ``project_id`` (str): Limit to tasks in this project. Accepts the project's name as well as its ID (case-insensitive, trimmed). Two projects sharing a name is an error, not a guess, and so is a project the account does not have. * ``priority`` (int): 0=None, 1=Low, 3=Medium, 5=High. Must be a JSON integer; the string ``"3"`` and the float ``3.0`` are errors, as is any other value. * ``tag_label`` (str): Tag name (case-sensitive), non-empty. Surrounding whitespace is trimmed. * ``due_start_date`` / ``due_end_date`` (str): ISO date or…

Dump everything of a single kind from the local sync state. Args: search (str): Either ``"tasks"``, ``"projects"`` or ``"tags"`` (case-insensitive). detail (str, optional): ``"compact"`` (default) or ``"full"``. Accepted for parity with the other list tools and validated here. It has no effect on the ``"projects"``/``"tags"`` searches (those return non-task records in full) nor on the currently inert ``"tasks"`` search -- for a compact task list use ``ticktick_filter_tasks`` or ``ticktick_get_tasks_from_project``. Returns: For ``"projects"``: JSON list, inbox prepended as ``{"id": <inbox>, "name": "Inbox"}``. For ``"tags"``: JSON list of tag objects. For ``"tasks"``: see Limitations. Unknown search type: ``{"error": "Invalid search type...", "status": "error"}``. Limitations: - ``"tasks"`` triggers a fetch of every open task across all projects, but the current implementation returns ``None`` rather than a JSON string. Use ``ticktick_filter_tasks({"status": "uncompleted"})`` for a proper (compact) JSON response. Example: ticktick_get_all(search="projects")

Look up any object (task, project, tag) by its ID. Args: obj_id (str): The object's full ID. Returns: JSON object of the matching record, or an empty object ``{}`` if nothing has that id. Branch on emptiness. On failure: ``{"error": "...", "status": "error"}``. Freshness: Local state is synced from the server at most once per throttle window (default 15s, ``TICKTICK_MCP_SYNC_TTL_SECONDS``); an edit made elsewhere within that window may not be visible yet. Call ``ticktick_sync`` to force an immediate refresh. Example: ticktick_get_by_id(obj_id="60ca9dbc8f08516d9dd56324")

Return every open task in a project. Args: project_id (str): The project's ID or name. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. List them with ``ticktick_get_all(search="projects")``. detail (str, optional): ``"compact"`` (default) or ``"full"``. Compact drops the heavy ``content``/``desc``/checklist ``items`` blobs and bulky sync metadata, keeping id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags plus a ``contentPreview`` (first ~200 chars of content) so keyword search still works. Full returns the raw task objects unchanged. Returns: Compact (default): JSON list of compact task objects. If the compact payload would still exceed the size budget, the soonest-due tasks are returned and a final ``_truncation_note`` element reports how many were omitted -- nothing is dropped silently. Full: JSON list of raw task objects (empty list if none). On failure: ``{"error": "...", "status": "error"}``. Limitations: - Completed tasks are NOT included. - Compact output is for browsing only. To edit a task, call ``ticktick_update_task`` with its id and only the fields to change. Get the full content of a single task with ``ticktick_get_by_id``, or pass ``detail="full"``. Freshness: Local state is synced from the server at most once per throttle window (default 15s, ``TICKTICK_MCP_SYNC_TTL_SECONDS``); an edit made elsewhere within that window may not be visible yet. Call ``ticktick_sync`` to force an immediate refresh. Example: ticktick_get_tasks_from_project( project_id="<your-project-id>" )

Returns completed tasks for a project that have NOT yet been marked as processed by a domain agent. Could be called at the beginning of each conversation to check for new completions. After reviewing each returned task, call ticktick_mark_completion_processed to record that it has been handled. A task completed through ticktick_complete_task is recorded by that tool, so what this returns is what was completed elsewhere, in the TickTick app or on another client, where a note may be waiting to be read. One exception: no recurring completion is recorded, because it files its completed instance under an id the completing call never sees, so that instance appears here whoever completed it. Args: project_id (str): TickTick project ID or name to check. Required. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. days (int): How many days back to look for completions. Default 30. Returns: JSON list of unprocessed task objects (may be empty). Each object includes: id, title, projectId, completedTime, content. Error: {"error": "...", "status": "error"} Usage Guide: - Call once per project at the start of each conversation. - For each returned task: read the content field, log meaningful outcomes if appropriate, then call ticktick_mark_completion_processed. - Example: ticktick_get_unprocessed_completions( project_id="your_project_id_here", days=30 )

Nest ``child_task_id`` under ``parent_task_id``. Args: parent_task_id (str): The parent task's ID. child_task_id (str): The task to become a subtask. Must differ from ``parent_task_id`` and live in the same project. Returns: On success: ``{"status": "success", "updated_parent_task": ..., "api_response": ...}``. Missing child / parent: ``{"status": "not_found", "error": "..."}``. Cross-project: ``{"error": "...same project...", "child_project": "...", "parent_project": "..."}``. Example: ticktick_make_subtask( parent_task_id="60ca9dbc8f08516d9dd56324", child_task_id="60ca9dbc8f08516d9dd56325", )

Records that a domain agent has processed a completed task. Call this after reviewing each task returned by ticktick_get_unprocessed_completions. The task will no longer appear in future calls to that tool. Args: task_id (str): Full TickTick task ID. Required. project_id (str): Project ID or name the task belongs to. Required. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. title (str, optional): Task title (stored for human-readable audit trail). completed_time (str, optional): ISO completion timestamp from the task object. notes (str, optional): Brief notes on how the completion was handled. Returns: {"status": "ok", "task_id": "..."} on success. {"status": "already_processed", "task_id": "..."} if already recorded. {"error": "...", "status": "error"} on failure. Usage Guide: - Call once per task after finishing your handling of it. - Example: ticktick_mark_completion_processed( task_id="abc123", project_id="your_project_id_here", title="Fix kitchen tap", completed_time="2025-06-01T19:00:00+01:00", notes="Replaced ceramic disc, resolved" )

Move a task into a different project. Args: task_id (str): The task's full ID. new_project_id (str): Destination project's ID or name. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. Returns: JSON object containing the moved task. If the target project cannot be looked up locally, the move is still attempted. Missing source task (no projectId field): ``{"status": "not_found", ...}``. Other failures: ``{"error": "...", "status": "error"}``. Example: ticktick_move_task( task_id="60ca9dbc8f08516d9dd56324", new_project_id="<your-project-id>", )

Force an immediate refresh of TickTick state from the server. The active-read tools (``ticktick_get_by_id``, ``ticktick_get_tasks_from_project``, ``ticktick_filter_tasks``) already auto-refresh at most once per throttle window (default 15s, overridable via ``TICKTICK_MCP_SYNC_TTL_SECONDS``). Call this when you need an immediate refresh -- e.g. you just changed something in the TickTick app on another device, or a read looks stale and you want to be certain before acting. Returns: ``{"status": "synced", "task_count": N, "project_count": M}`` on success. ``{"status": "error", "detail": "..."}`` if the refresh failed -- the previous (stale) state is still served by the read tools, so callers can continue with reduced confidence. Example: ticktick_sync()

Update an existing task without wiping unmodified fields. Send only the fields to change. The tool fetches the current task and overlays ONLY the fields the caller explicitly set (``exclude_unset=True``), sending the other editable fields back with them. Args: task_object (TaskObject): Must include ``id``. All other fields are optional; set only the ones you want to change. When ``dueDate`` is set you must also set ``expectedDayOfWeek``. Returns: JSON object containing the updated task. ``_verification_warnings`` is attached when the response did not match what we sent, when a ``reminders: []`` removal could not be confirmed, and when ``status: 0`` was set but the local completion record could not be cleared. That last one says nothing about whether the update itself landed. On failure: ``{"error": "...", "status": "error"}``. Limitations: - Read-only API fields (``creator``, ``etag``, ``createdTime``, ``modifiedTime``, ``deleted``, ``kind``, ``isFloating``) are stripped from the main update call. - Setting ``status: 0`` also clears any local record of this task's earlier completion, so a later completion is surfaced by ``ticktick_get_unprocessed_completions`` again. A clear that fails is reported in ``_verification_warnings``. - ``reminders: []`` removes whatever reminders the task has at that moment, so do not send it back from an old copy of the task. ``_verification_warnings`` says so if the removal could not be confirmed. ``reminders: null`` leaves them alone. A non-empty list replaces them. Sending ``dueDate`` and ``startDate`` as ``null`` removes the date, and its reminders with it. Agent Usage Guide: - To reschedule a task, send a single update with the new ``dueDate`` + ``expectedDayOfWeek``. Do NOT complete and recreate. Example: ticktick_update_task(task_object={ "id": "60ca9dbc8f08516d9dd56324",…