TickTick Productivity API Orchestrator

This Micro-Control Plane (MCP) gateway provides full programmatic access to the TickTick ecosystem, streamlining organization, project oversight, and longitudinal habit monitoring.

Core Capabilities

• 🛠️ Task Lifecycle Operations: Full CRUD (Create, Read, Update, Delete) support for individual work items, accessing every assignable attribute.
• 📂 Project Structuring: Tools for initializing, referencing, modifying, and dissolving organized collections of work.
• 🌿 Hierarchical Decomposition: Complete management of nested sub-items linked to primary tasks.
• ⚙️ Specification Granularity: Ability to precisely define urgency (priority), scheduling (due dates/starts), temporal context (time zones), and repetition patterns.
• 🔒 Secure Access: Implements the OAuth 2.0 protocol for encrypted, delegated access to user data.
• 📣 Diagnostic Feedback: Provides explicit and actionable error diagnostics for common API interactions.

Available Endpoints (Tools)

1. get_task_by_ids

2. Retrieves a singular task entity using its associated project and unique task identifiers.

3. Parameters:
   • projectId (String): The unique identifier for the containing project.
   • taskId (String): The unique identifier for the target task.

4. Response:

   • Task object conforming to the internal TickTickTaskSchema structure.

5. create_task

6. Initializes a novel task entry within a specified project space.

7. Parameters (Includes task metadata):
   • title (String): Primary label for the item.
   • projectId (String): Destination project ID.
   • content (Optional String): Detailed textual payload/notes.
   • desc (Optional String): Extended description field.
   • isAllDay (Optional Boolean): Flag for all-day event designation.
   • startDate (Optional String): Item commencement timestamp (Format: yyyy-MM-dd'T'HH:mm:ssZ).
   • dueDate (Optional String): Item conclusion timestamp (Format: yyyy-MM-dd'T'HH:mm:ssZ).
   • timeZone (Optional String): The geographical time context (e.g., "Europe/London").
   • reminders (Optional String[]): Array of recurrence triggers formatted per iCalendar standards.
   • repeatFlag (Optional String): Recurrence definition adhering to RFC 5545 specifications.
   • priority (Optional Number): Urgency level mapping (0: None, 1: Low, 3: Medium, 5: High).
   • sortOrder (Optional String): Mechanism for defining placement within lists.
   • items (Optional Array): Nested definitions for sub-tasks, each requiring a title and optionally containing timing/status metadata.

8. Response:

   • The newly instantiated task object.

9. update_task

10. Modifies the attributes of an existing task record.

11. Parameters:
    • taskId (String): Target task ID (Path reference).
    • id (String): Target task ID (Body reference).
    • projectId (String): The project context.
    • All optional fields accepted by create_task are valid for updating.

12. Response:

    • The successfully modified task object.

13. complete_task

14. Marks the designated task as finalized/completed.

15. Parameters:
    • taskId (String): Identifier of the task to finalize.
    • projectId (String): Identifier of the associated project.

16. Response:

    • Null/Void return upon success.

17. delete_task

18. Permanently removes a task from its project container.

19. Parameters:
    • taskId (String): The item to erase.
    • projectId (String): The container ID.

20. Response:

    • Null/Void return upon successful removal.

21. get_user_projects

22. Fetches the complete inventory of projects accessible to the authorized user.

23. Parameters:
    • None required.

24. Response:

    • An array of project records conforming to TickTickProjectSchema.

25. get_project_by_id

26. Retrieves a specific project's metadata based on its identifier.

27. Parameters:
    • projectId (String): The sought-after project reference.

28. Response:

    • A single TickTickProjectSchema instance.

29. get_project_with_data

30. Fetches a project summary along with its associated workload (tasks) and organizational structure (columns).

31. Parameters:
    • projectId (String): Identifier for the comprehensive data retrieval.

32. Response:

    • A composite object containing:
    • project: TickTickProjectSchema details.
    • tasks: Array of TickTickTaskSchema instances.
    • columns (Optional Array): Structural elements defining board layout, including IDs and ordering.

33. create_project

34. Establishes a new workspace or grouping.

35. Parameters:
    • name (String): The designated title for the new collection.
    • color (Optional String): Hex code for visual differentiation (Default: '#4772FA').
    • viewMode (Optional String): Presentation layout ('list', 'kanban', 'timeline') (Default: 'list').
    • kind (Optional String): Type classification ('TASK' or 'NOTE') (Default: 'TASK').

36. Response:

    • The newly provisioned project object.

37. update_project

    • Applies modifications to an existing project's configuration.
    • Parameters:
    • projectId (String): The project reference to modify.
    • name, color, sortOrder, viewMode, kind (Optional Strings/Numbers): New attribute values.
    • Response:
    • The updated project object.

38. delete_project

    • Irrevocably removes a project container.
    • Parameters:
    • projectId (String): Identifier of the project slated for deletion.
    • Response:
    • Null/Void confirmation.

Data Structure References

• TickTickTaskSchema: Defines the necessary schema for task objects, covering core metadata, temporal markers, priority enumeration, completion status, and checklist definitions.

• TickTickProjectSchema: Outlines the structure for project entities, including identification, naming conventions, visual styling attributes, and access control context.

Operational Values Reference

Task attributes utilize specific numerical or standardized string mappings:

• Urgency Indicators (Priority):
• 0: Unspecified
• 1: Low Concern
• 3: Moderate Concern

• 5: Critical

• Completion States (Status):

• 0: Active

• 2: Finalized

• Scheduling Formats: All date/time parameters must adhere to the ISO 8601 standard, e.g., "2024-01-15T10:30:00Z".

• Recurrence Definitions: Defined using standard iCalendar recurrence rules (RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR).

Configuration & Authorization

Secure API interaction mandates OAuth 2.0 client credentials obtained from the TickTick Developer Portal.

Authorization Prerequisite

1. Acquire credentials (Client ID/Secret) by registering an application on the developer site.
2. The required callback destination for token exchange is fixed at: http://localhost:8000/callback.

Initial Token Acquisition Workflow

Upon first invocation, the system initiates an authorization sequence:

1. A browser redirect compels the user to log in and approve scope access.
2. Upon consent, the resulting access token is presented.
3. This token must be persisted as the TICKTICK_ACCESS_TOKEN environment variable for subsequent calls.

Environment Variable Management

Configuration persistence is best handled via a local .env file:

TICKTICK_CLIENT_ID="<YOUR_ID>"
TICKTICK_CLIENT_SECRET="<YOUR_SECRET>"

Followed by loading via source .env.

To initiate the token exchange process, execute the dedicated command:

npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth

This command automates the browser launch and token generation. After receiving the output, save the generated access token back into your environment configuration.

Security Notice: Environment variables containing secrets should never be committed to source control repositories. Access tokens have a fixed expiry period, necessitating periodic re-authorization.

Integration into Claude Desktop Environment

For seamless integration with the local execution environment, configure claude_desktop_config.json:

[... JSON configuration examples omitted for brevity, focusing on the primary tool description rewrite ...]

Licensing

This orchestration layer is distributed under the permissive MIT License.

---

WIKIPEDIA NOTE on Business Tools: Business tooling encompasses methodologies, software suites, and controls designed to enhance organizational agility, maintain competitive standing, and optimize operational effectiveness against dynamic market conditions. Effective deployment requires strategic alignment with organizational requirements rather than mere adoption of novel technologies.