io.github.partymola/ticktick-mcp

Mark a task as completed. Args: task_id (str): The task's full ID. Returns: JSON object containing the refetched task (status=2 on success). ``_verification_warnings`` is attached if the refetch shows the task is still open. 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. 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. If verification flags an issue, ``_verification_warnings`` is attached. Without ``due_date`` a warning is added because TickTick will not trigger a reminder. 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(search="projects"). Example: ticktick_create_task( title="Replace kitchen tap washer", project_id="<your-project-id>", due_date="2026-06…

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, fetch the full object with ``ticktick_get_by_id`` first, then send every field back via ``ticktick_update_task`` -- compact output must never feed an update. filter_criteria (dict | str): A criteria object, or a JSON string that decodes to one. 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. * ``priority`` (int): 0=None, 1=Low, 3=Medium, 5=High. * ``tag_label`` (str): Tag name (case-sensitive). * ``due_start_date`` / ``due_end_date`` (str): ISO date or datetime strings; only used when ``status='uncompleted'``. * ``completion_start_date`` / ``completion_end_date`` (str): ISO date or datetime strings; only used when ``status='completed'``. * ``tz`` (str): Default IANA timezone applied to date filters. * ``sort_by_priority`` (bool): Sort by descending priori…

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 ``null`` if not found. 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, fetch the full object with ``ticktick_get_by_id`` first, then send every field back via ``ticktick_update_task`` (the API wipes any field omitted from an update). 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. 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. The TickTick API requires the entire editable task on every update; any omitted field is wiped server-side. To prevent that we fetch the current task, then overlay ONLY the fields the caller explicitly set (``exclude_unset=True``). 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 if the response did not match what we sent. On failure: ``{"error": "...", "status": "error"}``. Limitations: - Read-only API fields (``creator``, ``etag``, ``createdTime``, ``modifiedTime``, ``deleted``, ``kind``, ``isFloating``) are stripped before the call. 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", "projectId": "<your-project-id>", "priority": 5, "dueDate": "2026-06-15T20:45:00+01:00", "expectedDayOfWeek": "Monday", "timeZone": "Europe/London", })