trackmcp
Back to directory
jen6

ticktick-mcp

View on GitHub

Enhance your TickTick workflow with MCP server. Better filtering interface

35 stars PythonServers & Infrastructure Updated Nov 3, 2025

Documentation

TickTick MCP Server

License: MIT

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` library 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:

    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 `.env` file should contain:

      dotenv
      TICKTICK_CLIENT_ID=your_client_id   # Obtained in Step 1
       TICKTICK_CLIENT_SECRET=your_client_secret # Obtained in Step 1
       TICKTICK_REDIRECT_URI=your_redirect_uri # Entered in Step 1 (must match exactly)
       TICKTICK_USERNAME=your_ticktick_email # Your TickTick login email
       TICKTICK_PASSWORD=your_ticktick_password # Your TickTick login password (or app password if enabled)

      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.

        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:

        json
        {
         "mcpServers": {
         "ticktick": {
          "command": "uvx",
          "args": [
          "--from",
          "git+https://github.com/jen6/ticktick-mcp.git",
          "ticktick-mcp"
          // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
          // but standard clients might not support passing extra args easily.
          ]
         }
         }
        }

        🔧 Tools

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

        Task Management

        1. `ticktick_create_task`

          2. `ticktick_update_task`

            3. `ticktick_delete_tasks`

              4. `ticktick_complete_task`

                5. `ticktick_move_task`

                  6. `ticktick_make_subtask`

                    Task Retrieval

                    7. `ticktick_get_by_id`

                      8. `ticktick_get_all`

                        9. `ticktick_get_tasks_from_project`

                          10. `ticktick_filter_tasks`

                            Helper Tools

                            11. `ticktick_convert_datetime_to_ticktick_format`

                              🤖 Sample agent prompt

                              code
                              ## Persona: Daily Stand-up Agent
                              
                              - **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
                              - **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks
                              
                              ---
                              
                              ## Core Features & Workflow
                              
                              1. **Fetch Current Time** 
                               - Retrieve current time using `time mcp`.
                              
                              2. **Session Start & Data Loading** 
                               - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
                               - Call TickTick MCP API to fetch all tasks due **today**. 
                               - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").
                              
                              3. **Daily Briefing**
                               Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:
                              
                               **Tasks Due Today:**
                               - Task Name 1
                               - Task Name 2
                               …
                              
                               **Overdue Tasks:**
                               - Task Name 3
                               - Task Name 4
                               …
                              
                              4. **Select Key Task** 
                               > "Which of these tasks would you like to focus on first or must complete today? 
                               > Or is there another important task you'd like to add?"
                              
                              5. **Task Breakdown (Subtask Creation)** 
                               - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
                               - Example (if "Write project report" is selected):
                                1. Draft outline & table of contents (10 min) 
                                2. Gather & analyze data (30 min) 
                                3. Write section drafts (1 h) 
                                4. Review & revise draft (30 min) 
                                5. Final submission (10 min)
                              
                              6. **Confirm & Add Subtasks** 
                               - Ask the user to confirm or adjust the suggested subtasks: 
                                > "Does this breakdown look good? Any changes?" 
                               - Once approved, call MCP to add each subtask to TickTick, setting them as children of the main task if supported, naming them "[Main Task] – [Subtask]". 
                               mcp.ticktick.addTask({
                                name: "[Main Task] – [Subtask]",
                                parentId: "..."
                               });
                              
                              7. **Session Close** 
                               > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"
                              
                              ---
                              
                              ## Additional Guidelines
                              
                              - **Tone & Manner**: Friendly, proactive, and organized. 
                              - **MCP Interface Examples**: 
                               // Fetch today's due tasks
                               mcp.ticktick.getTasks({
                               filter_criteria: {
                                status: "uncompleted",
                                tz: "Asia/Seoul",
                                due_end_date: "2025-04-29"
                               }
                               });
                              
                               // Add a subtask
                               mcp.ticktick.addTask({
                               name: "Project Report – Write Draft",
                               parentId: "task123"
                               });
                              - **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
                              - **Clarity**: Present task lists and subtask suggestions clearly. 
                              - **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.

                              🤝 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

                              Frequently asked questions

                              What is ticktick-mcp?

                              ticktick-mcp is Enhance your TickTick workflow with MCP server. Better filtering interface

                              How do I install ticktick-mcp?

                              Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

                              Is ticktick-mcp open source?

                              Yes — it is hosted on GitHub at https://github.com/jen6/ticktick-mcp and has 35 stars.

                              Related MCP tools

                              Run your own MCP server? See who uses it and what to fix.

                              Measure it with TrackMCP