TickTick MCP Server

Enhance your TickTick workflow with this MCP server. Built upon the ticktick-py library, it offers significantly improved filtering capabilities, allowing AI assistants and MCP-compatible applications (like Claude Desktop, VS Code Agent Mode, or mcp-use) to interact with your tasks with greater precision and power.

✨ Features

This server provides comprehensive access to TickTick functionalities via MCP tools, categorized as follows:

• Task Management: Create, update (including conversion to TickTick's date format), delete, complete, and move tasks.

• Subtask Management: Create subtasks by linking existing tasks.

• Task Retrieval:

  • Get all uncompleted tasks.

  • Get tasks by ID or specific fields.

  • Get completed tasks within a date range.

  • Get tasks from a specific project.

  • Filter tasks based on various critggeria (priority, project, tags, etc.).

• Project/Tag Management: Retrieve all projects, tags, and project folders.

• Helper Tools: Convert datetime strings to the required TickTick format.

Refer to the tool definitions within the src/ticktick_mcp/tools/ directory for detailed specifications.

🚀 Getting Started

This server utilizes the unofficial ticktick-py to interact with the TickTick API.

Prerequisites

• Python >= 3.10

• Access to TickTick and API credentials (see below).

Setup

1. Register a TickTick Application: Before using the server, you need to register an application with TickTick to obtain API credentials. Follow these steps based on the ticktick-py documentation:

   • Go to the TickTick OpenAPI Documentation and log in with your TickTick account.

   • Click on Manage Apps in the top right corner.

   • Register a new app by clicking the +App Name button. Provide a name for your application (e.g., "MCP Server").

   • Once created, edit the app details. Note down the generated Client ID and Client Secret.

   • For the OAuth Redirect URL, enter a URL where you want to be redirected after authorizing the application. It doesn't need to be a live URL

     • http://localhost:8080/redirect or http://127.0.0.1:8080/ are common choices for local development.

     • Ensure this exact URL is saved in your environment variables.

2. Environment Variables: The server requires the TickTick API credentials you just obtained, plus your TickTick login details. By default, it looks for a .env file located at ~/.config/ticktick-mcp/.env.

   • The server might create the ~/.config/ticktick-mcp/ directory if it doesn't exist, but it's safer to create it manually.

   • You must create the within that directory.

   • Alternatively, you can specify a different directory using the --dotenv-dir command-line argument only when running the server directly via Python (see "Running the Server" below).

   The .env file should contain:

3. Authentication (First Run): On the first run (either directly or via an MCP client), the underlying ticktick-py library will initiate an OAuth2 authentication flow.

   • A web browser window might open automatically, or a URL will be printed in the console/log output.

   • You need to visit this URL, log in to TickTick if necessary, and authorize the application (granting Read and Write permissions).

   • After authorization, you will be redirected to the TICKTICK_REDIRECT_URI you specified.

     • The console will prompt you to paste this full redirected URL (which includes a code= parameter) back into the terminal.

   • Upon successful verification, a .token-oauth file will be created in the same directory as your .env file.

   • This file caches the authorization token, so you typically only need to perform this manual authorization step once every ~6 months or if the token becomes invalid.

Running the Server

You can run the server in two main ways:

1. Via an MCP Client (Recommended for AI Assistant Integration):

Configure your MCP client (like Claude Desktop, VS Code Agent Mode, etc.) to use the server. Example configuration:

🔧 Tools

This server provides the following tools for interacting with the TickTick task management service:

Task Management

1. ticktick_create_task

   • Creates a new task in TickTick

   • Inputs:

     • title (string): The title of the task. Required.

     • projectId (string, optional): ID of the project to add the task to.

     • content (string, optional): Additional details or notes for the task.

     • desc (string, optional): Description for the task.

     • allDay (boolean, optional): Set to True if the task spans the entire day.

     • startDate (string, optional): Start date/time in ISO 8601 format.

     • dueDate (string, optional): Due date/time in ISO 8601 format.

     • timeZone (string, optional): IANA timezone name (e.g., 'Asia/Seoul').

     • reminders (array of strings, optional): List of reminder triggers in RFC 5545 format.

     • repeat (string, optional): Recurring rule in RFC 5545 format.

     • priority (integer, optional): Task priority (0=None, 1=Low, 3=Medium, 5=High).

     • sortOrder (integer, optional): Custom sort order value.

     • items (array of objects, optional): List of subtask dictionaries.

2. ticktick_update_task

   • Updates an existing task

   • Inputs:

     • task_object (object): A dictionary with task properties to update including the task id.

3. ticktick_delete_tasks

   • Deletes one or more tasks

   • Inputs:

     • task_ids (string or array of strings): A single task ID or list of task IDs to delete.

4. ticktick_complete_task

   • Marks a task as complete

   • Inputs:

     • task_id (string): The ID of the task to mark as complete.

5. ticktick_move_task

   • Moves a task to a different project

   • Inputs:

     • task_id (string): The ID of the task to move.

     • new_project_id (string): The ID of the destination project.

6. ticktick_make_subtask

   • Makes one task a subtask of another

   • Inputs:

     • parent_task_id (string): The ID of the task that will become the parent.

     • child_task_id (string): The ID of the task that will become the subtask.

Task Retrieval

7. ticktick_get_by_id

   • Retrieves a specific object (task, project, etc.) by ID

   • Inputs:

     • obj_id (string): The unique ID of the object to retrieve.

8. ticktick_get_all

   • Retrieves all objects of a specified type

   • Inputs:

     • search (string): The type of objects to retrieve (e.g., 'tasks', 'projects', 'tags').

9. ticktick_get_tasks_from_project

   • Retrieves all uncompleted tasks from a specific project

   • Inputs:

     • project_id (string): The ID of the project.

10. ticktick_filter_tasks

    • Filters tasks based on various criteria

    • Inputs:

      • filter_criteria (object): Dictionary with filtering parameters such as:

        • status (string): Task status ('uncompleted' or 'completed').

        • project_id (string, optional): Project ID to filter tasks by.

        • tag_label (string, optional): Tag name to filter tasks by.

        • priority (integer, optional): Priority level.

        • due_start_date (string, optional): ISO format start date for due date filter.

        • due_end_date (string, optional): ISO format end date for due date filter.

        • completion_start_date (string, optional): Start date for completion date filter.

        • completion_end_date (string, optional): End date for completion date filter.

        • sort_by_priority (boolean, optional): Sort results by priority.

        • tz (string, optional): Timezone for date interpretation.

Helper Tools

11. ticktick_convert_datetime_to_ticktick_format

    • Converts ISO 8601 date/time string to TickTick API format

    • Inputs:

      • datetime_iso_string (string): The date/time string in ISO 8601 format.

      • tz (string): IANA timezone name to interpret the date/time.

🤖 Sample agent prompt

🤝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 See Also

• Model Context Protocol Servers: The central repository for reference implementations of MCP servers for various tools and platforms.

• modelcontextprotocol.io: Official documentation for the Model Context Protocol.

• pietrozullo/mcp-use: A popular Python library for building clients/agents that interact with MCP servers.

• lazeroffmichael/ticktick-py: The unofficial TickTick API library used by this project to handle authentication and API interactions.