TickTick Workflow Conductor Server

Elevate your productivity regimen through this dedicated MCP endpoint for TickTick. Leveraging the robust ticktick-py foundation, this server exposes significantly augmented data retrieval mechanisms, empowering AI agents and compliant applications (such as Claude Desktop, VS Code Agent Mode, or mcp-use) to manipulate your to-do items with unprecedented precision and operational scope.

✨ Core Capabilities

This service furnishes comprehensive programmatic entry points to TickTick's features via MCP interfaces, structured as follows:

• Task Lifecycle Management: Functionality to instantiate, modify (including automated date format serialization for the API), retire, finalize (mark as done), and relocate tasks.
• Hierarchical Structuring: Mechanism to establish child tasks linked to existing parent items.
• Data Fetching & Querying:
• Retrieve all currently active (uncompleted) entries.
• Fetch items based on their unique identifier or specific attribute values.
• Query completed items within defined temporal boundaries.
• Isolate entries belonging to a particular organizational container (project).
• Execute complex transactional searches using composite predicates (e.g., priority, associated tag, project membership).
• Metadata Access: Routines for querying organizational structures: fetching all projects, available tags, and project folder groupings.
• Utility Functions: Conversion routines to translate standard datetime notations into TickTick's proprietary API format.

Detailed function signatures and input schemas are delineated within the src/ticktick_mcp/tools/ directory.

🚀 Deployment Guide

This orchestration layer relies on the community-maintained ticktick-py abstraction layer for API communication.

Prerequisites

• Python runtime version 3.10 or newer.
• Valid TickTick access credentials and authorization tokens.

Setup Procedure

1. TickTick Application Registration: Prior to deployment, you must register a service application within TickTick to secure necessary authorization tokens. Adhere to the instructions provided by the ticktick-py documentation:

   • Navigate to the TickTick OpenAPI Portal and authenticate with your user credentials.
   • Locate and utilize the Manage Apps interface (top-right corner).
   • Register a new entity (e.g., "MCP Conductor").
   • Upon creation, extract and secure the resulting Client ID and Client Secret.
   • Specify the OAuth Redirect URL. This URL does not require live hosting for initial setup:
   • Standard local settings: http://localhost:8080/redirect or http://127.0.0.1:8080/.
     • Crucially, this exact URI must be mirrored in your environment configuration.

2. Configuration Environment Variables: The server necessitates credential loading, ideally via a configuration file. By default, it searches for .env inside ~/.config/ticktick-mcp/.

   • While the server might auto-create the configuration directory, manual initialization is advised.
   • The .env file must be provisioned by the user within that specified location.
   • Alternatively, command-line arguments (--dotenv-dir) permit overriding the location when executing the server binary directly.

   The required structure for the .env file is: dotenv TICKTICK_CLIENT_ID=your_client_id # From Step 1 TICKTICK_CLIENT_SECRET=your_client_secret # From Step 1 TICKTICK_REDIRECT_URI=your_redirect_uri # Must precisely match the URL entered in Step 1 TICKTICK_USERNAME=your_ticktick_email # Your primary TickTick email TICKTICK_PASSWORD=your_ticktick_password # Your password or app-specific token

3. Authorization Handshake (Initial Execution): The first invocation, whether direct or via an MCP client, triggers the OAuth2 authorization sequence.

   • An interactive web session will initiate, potentially opening a browser or outputting an authorization URL to the log/console.
   • Access this URL, log in, and formally grant the necessary Read/Write permissions to the registered application.
   • Upon successful consent, the user is redirected to the configured TICKTICK_REDIRECT_URI.
   • The console will then demand that the user copy and paste the entire resulting URL (which contains the authorization code=) back into the terminal.
   • Successful validation results in the persistent caching of the authorization token within a .token-oauth file, created alongside the .env file. This token typically remains valid for approximately six months, minimizing subsequent manual intervention.

Launching the Service

Operation is typically managed through an external MCP client:

1. Integration via MCP Host (Recommended for Agent Deployments):

Configure your orchestration host (e.g., Claude Desktop, VS Code Agent Mode) using a configuration similar to this structure:

{ "mcpServers": { "ticktick": { "command": "uvx", "args": [ "--from", "git+https://github.com/jen6/ticktick-mcp.git", "ticktick-mcp" // Additional arguments like --dotenv-dir are client-dependent ] } } }

🔧 Toolset Reference

This server exposes the following interface functions for TickTick operations:

Task Manipulation

1. ticktick_create_task
2. Instantiates a new task entity.

3. Inputs:

   • title (string): Mandatory name for the entry.
   • projectId (string, optional): Identifier for the parent project container.
   • content (string, optional): Supplementary notes or long-form text.
   • desc (string, optional): Alias for task description content.
   • allDay (boolean, optional): Designates event spanning the whole day.
   • startDate (string, optional): Initial date/time, formatted as ISO 8601.
   • dueDate (string, optional): Deadline date/time, formatted as ISO 8601.
   • timeZone (string, optional): IANA standard designation (e.g., 'America/Los_Angeles').
   • reminders (array of strings, optional): List of scheduled alerts formatted per RFC 5545.
   • repeat (string, optional): Recurrence rule specification per RFC 5545.
   • priority (integer, optional): Urgency ranking (0=None, 1=Low, 3=Medium, 5=High).
   • sortOrder (integer, optional): Custom ordering index.
   • items (array of objects, optional): Array defining nested subtasks.

4. ticktick_update_task

5. Modifies an extant task record.

6. Inputs:

   • task_object (object): Comprehensive dictionary of properties to alter, must include the task id.

7. ticktick_delete_tasks

8. Permanently removes specified tasks.

9. Inputs:

   • task_ids (string or array of strings): Single or multiple unique task identifiers targeted for removal.

10. ticktick_complete_task

11. Marks an item's status as finished.

12. Inputs:

    • task_id (string): The unique identifier of the target task.

13. ticktick_move_task

14. Reassigns a task to a different project structure.

15. Inputs:

    • task_id (string): Identifier of the task being relocated.
    • new_project_id (string): Identifier of the target destination project.

16. ticktick_make_subtask

17. Establishes a hierarchical parent-child relationship.
18. Inputs:
    • parent_task_id (string): The ID designated as the superior task.
    • child_task_id (string): The ID designated as the subordinate task.

Data Retrieval

1. ticktick_get_by_id
2. Fetches a singular entity (task, project, etc.) using its unique key.

3. Inputs:

   • obj_id (string): The globally unique identifier for the desired resource.

4. ticktick_get_all

5. Retrieves all instances of a specified resource type.

6. Inputs:

   • search (string): The entity classification to fetch (e.g., 'tasks', 'projects', 'tags').

7. ticktick_get_tasks_from_project

8. Retrieves all active tasks housed within a designated project container.

9. Inputs:

   • project_id (string): The identifier of the source project.

10. ticktick_filter_tasks

    • Executes advanced, multi-parameter querying against the task repository.
    • Inputs:
    • filter_criteria (object): A map containing filtering parameters:
      • status (string): State filter ('uncompleted' or 'completed').
      • project_id (string, optional): Filter by specific project container ID.
      • tag_label (string, optional): Filter by the name of an associated tag.
      • priority (integer, optional): Filter by urgency level.
      • due_start_date (string, optional): Temporal boundary (start) for due date inclusion (ISO format).
      • due_end_date (string, optional): Temporal boundary (end) for due date inclusion (ISO format).
      • completion_start_date (string, optional): Start range for items marked complete.
      • completion_end_date (string, optional): End range for items marked complete.
      • sort_by_priority (boolean, optional): Instruction to order results by priority level.
      • tz (string, optional): Timezone context for date evaluation.

Auxiliary Functions

1. ticktick_convert_datetime_to_ticktick_format
   • Translates standard ISO 8601 timestamps into the specific string format required by the TickTick service API.
   • Inputs:
   • datetime_iso_string (string): The input date/time provided in ISO 8601 notation.
   • tz (string): The IANA timezone identifier used for interpreting the source time.

🤖 Illustrative Agent Prompting Scenario

Persona: Daily Operational Briefing Agent

• Designation: AI orchestrator linked to the user's TickTick data repository, focused on synthesizing daily commitments.
• Primary Mandate: To streamline the user's commencement of daily activities, emphasizing high-priority items and facilitating task decomposition.

---

Execution Flow Model

1. Temporal Context Retrieval

2. Secure the present moment utilizing the time mcp service.

3. Initialization & Data Ingestion

4. The interaction commences with a directive such as "Initiate daily review" or simply "Good day."
5. Execute the TickTick MCP call to fetch all tasks scheduled for today's completion.

6. Provide user feedback regarding the data fetching process (e.g., "Syncing today's critical and overdue items from TickTick...").

7. Daily Synopsis Delivery Good morning! The current epoch is {YYYY-MM-DD}. Your TickTick summary:

Commitments Due Today: - Item Alpha - Item Beta …

Backlog Items Overdue: - Item Gamma - Item Delta …

1. Focus Selection Prompt

   "Which of these assignments requires your immediate concentration, or do you have an unscheduled critical item that needs inclusion?"

2. Decomposition Planning (Subtask Generation)

3. Based on the user's selection of a major task, propose a granular execution plan consisting of 2 to 5 prerequisite steps.
4. Example (if "Develop Quarterly Forecast" is selected):
5. Outline structure and necessary variables (15 min)
6. Aggregate sales metrics data (45 min)
7. Construct preliminary financial models (1.5 h)
8. Draft executive summary narrative (45 min)

9. Final validation review (20 min)

10. Confirmation and Subtask Materialization

11. Solicit explicit user confirmation or request modification of the proposed decomposition:

    "Does this sequence align with your expectations? Any adjustments needed?"

12. Upon affirmative consent, invoke the MCP to create each subtask in TickTick, ensuring they are correctly nested under the parent task, utilizing a naming convention like "[Parent Task Name] – [Step Description]". mcp.ticktick.create_task({ title: "[Parent Task] – [Subtask Detail]", projectId: "...", // If applicable parentId: "..." // Parent task ID });

13. Session Termination

    "All necessary sub-steps have been logged in TickTick. Wishing you a productive session! Is there any further task coordination required?"

---

Operational Directives

• Demeanor: Approachable, preemptive, and highly structured.
• MCP Interaction Examples: // Fetching entries due on a specific date mcp.ticktick.filter_tasks({ filter_criteria: { status: "uncompleted", tz: "Europe/London", due_end_date: "2025-05-15" } });

// Adding a procedural step mcp.ticktick.make_subtask({ parent_task_id: "task987", child_task_id: "task988" // Assuming task988 was created first }); - Failure Management: Clearly communicate MCP execution errors to the user and recommend re-execution attempts. - Communication Standard: Maintain clarity when presenting inventory lists and procedural suggestions. - Pre-Action Planning: Utilize the sequential thinking mcp utility before committing any structural changes to the task database.

🤝 Collaboration Guidelines

We welcome contributions! Feel empowered to open an issue or submit a pull request for enhancements or corrections.

📜 Licensing Information

This software is distributed under the terms of the MIT License; consult the LICENSE file for comprehensive details.

🔗 Related Resources

• Model Context Protocol Repository: Official hub for reference implementations of MCP servers across various platforms.
• modelcontextprotocol.io: Official documentation for the Model Context Protocol specification.
• pietrozullo/mcp-use: A widely used Python utility for constructing clients capable of interacting with MCP endpoints.
• lazeroffmichael/ticktick-py: The underlying unofficial Python library managing TickTick API authentication and data exchange for this service.

WIKIPEDIA CONTEXT: Enterprise administration resources encompass the entire array of applications, governance frameworks, computational utilities, methodologies, etc., employed by organizations to successfully navigate evolving market dynamics, maintain competitive advantage, and optimize operational efficacy. These span departmental functions, including strategic forecasting, procedural management, record keeping, personnel management, arbitration, oversight, and control mechanisms. Modern organizational tools have undergone radical transformation due to rapid technological advancement, making the selection of optimal solutions complex amid continuous pressure to reduce overhead and boost revenues, while deeply understanding and fulfilling precise customer demands. Managers must adopt a strategic posture towards these instruments, ensuring they are custom-fitted to organizational requirements rather than adopting tools indiscriminately. Key tools frequently adopted globally include Strategic planning, Customer relationship management (CRM), Benchmarking, and Supply chain management systems.