TickTick MCP Server

1# TickTick MCP Server
2 
3<!-- Add relevant badges here -->
4[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5<!-- [![PyPI version](https://badge.fury.io/py/your-package-name.svg)](https://badge.fury.io/py/your-package-name) -->
6 
7![](images/ticktick_img.webp)
8 
9Enhance 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.
10 
11 
12 
13## ✨ Features
14 
15This server provides comprehensive access to TickTick functionalities via MCP tools, categorized as follows:
16 
17* **Task Management:** Create, update (including conversion to TickTick's date format), delete, complete, and move tasks.
18* **Subtask Management:** Create subtasks by linking existing tasks.
19* **Task Retrieval:**
20  *  Get all uncompleted tasks.
21  *  Get tasks by ID or specific fields.
22  *  Get completed tasks within a date range.
23  *  Get tasks from a specific project.
24  *  Filter tasks based on various critggeria (priority, project, tags, etc.).
25*  **Project/Tag Management:** Retrieve all projects, tags, and project folders.
26*  **Helper Tools:** Convert datetime strings to the required TickTick format.
27 
28Refer to the tool definitions within the `src/ticktick_mcp/tools/` directory for detailed specifications.
29 
30## 🚀 Getting Started
31 
32This server utilizes the unofficial [`ticktick-py` library](https://lazeroffmichael.github.io/ticktick-py/) to interact with the TickTick API.
33 
34### Prerequisites
35 
36*  Python >= 3.10
37*  Access to TickTick and API credentials (see below).
38 
39### Setup
40 
411. **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:
42    * Go to the [TickTick OpenAPI Documentation](https://developer.ticktick.com/docs#/openapi) and log in with your TickTick account.
43    *  Click on `Manage Apps` in the top right corner.
44    *  Register a new app by clicking the `+App Name` button. Provide a name for your application (e.g., "MCP Server").
45    *  Once created, edit the app details. Note down the generated `Client ID` and `Client Secret`.
46    *  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
47       *  `http://localhost:8080/redirect` or `http://127.0.0.1:8080/` are common choices for local development. 
48        * **Ensure this exact URL is saved in your environment variables.**
49 
502. **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`.
51    * The server *might* create the `~/.config/ticktick-mcp/` directory if it doesn't exist, but it's safer to create it manually.
52    * You **must create the `.env` file manually** within that directory.
53    * 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).
54 
55    The `.env` file should contain:
56 ```dotenv
57 TICKTICK_CLIENT_ID=your_client_id   # Obtained in Step 1
58 TICKTICK_CLIENT_SECRET=your_client_secret # Obtained in Step 1
59 TICKTICK_REDIRECT_URI=your_redirect_uri # Entered in Step 1 (must match exactly)
60 TICKTICK_USERNAME=your_ticktick_email # Your TickTick login email
61 TICKTICK_PASSWORD=your_ticktick_password # Your TickTick login password (or app password if enabled)
62 ```
63 
643. **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.
65    * A web browser window might open automatically, or a URL will be printed in the console/log output.
66    * You need to visit this URL, log in to TickTick if necessary, and authorize the application (granting Read and Write permissions).
67    * After authorization, you will be redirected to the `TICKTICK_REDIRECT_URI` you specified. 
68      * The console will prompt you to **paste this full redirected URL** (which includes a `code=` parameter) back into the terminal.
69    * Upon successful verification, a `.token-oauth` file will be created in the same directory as your `.env` file. 
70    * 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.
71 
72### Running the Server
73 
74You can run the server in two main ways:
75 
76**1. Via an MCP Client (Recommended for AI Assistant Integration):**
77 
78Configure your MCP client (like Claude Desktop, VS Code Agent Mode, etc.) to use the server. Example configuration:
79 
80```json
81{
82 "mcpServers": {
83 "ticktick": {
84  "command": "uvx",
85  "args": [
86  "--from",
87  "git+https://github.com/jen6/ticktick-mcp.git",
88  "ticktick-mcp"
89  // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
90  // but standard clients might not support passing extra args easily.
91  ]
92 }
93 }
94}
95```
96 
97## 🔧 Tools
98 
99This server provides the following tools for interacting with the TickTick task management service:
100 
101### Task Management
102 
1031. `ticktick_create_task`
104   * Creates a new task in TickTick
105   * Inputs:
106     * `title` (string): The title of the task. Required.
107     * `projectId` (string, optional): ID of the project to add the task to.
108     * `content` (string, optional): Additional details or notes for the task.
109     * `desc` (string, optional): Description for the task.
110     * `allDay` (boolean, optional): Set to True if the task spans the entire day.
111     * `startDate` (string, optional): Start date/time in ISO 8601 format.
112     * `dueDate` (string, optional): Due date/time in ISO 8601 format.
113     * `timeZone` (string, optional): IANA timezone name (e.g., 'Asia/Seoul').
114     * `reminders` (array of strings, optional): List of reminder triggers in RFC 5545 format.
115     * `repeat` (string, optional): Recurring rule in RFC 5545 format.
116     * `priority` (integer, optional): Task priority (0=None, 1=Low, 3=Medium, 5=High).
117     * `sortOrder` (integer, optional): Custom sort order value.
118     * `items` (array of objects, optional): List of subtask dictionaries.
119 
1202. `ticktick_update_task`
121   * Updates an existing task
122   * Inputs:
123     * `task_object` (object): A dictionary with task properties to update including the task `id`.
124 
1253. `ticktick_delete_tasks`
126   * Deletes one or more tasks
127   * Inputs:
128     * `task_ids` (string or array of strings): A single task ID or list of task IDs to delete.
129 
1304. `ticktick_complete_task`
131   * Marks a task as complete
132   * Inputs:
133     * `task_id` (string): The ID of the task to mark as complete.
134 
1355. `ticktick_move_task`
136   * Moves a task to a different project
137   * Inputs:
138     * `task_id` (string): The ID of the task to move.
139     * `new_project_id` (string): The ID of the destination project.
140 
1416. `ticktick_make_subtask`
142   * Makes one task a subtask of another
143   * Inputs:
144     * `parent_task_id` (string): The ID of the task that will become the parent.
145     * `child_task_id` (string): The ID of the task that will become the subtask.
146 
147### Task Retrieval
148 
1497. `ticktick_get_by_id`
150   * Retrieves a specific object (task, project, etc.) by ID
151   * Inputs:
152     * `obj_id` (string): The unique ID of the object to retrieve.
153 
1548. `ticktick_get_all`
155   * Retrieves all objects of a specified type
156   * Inputs:
157     * `search` (string): The type of objects to retrieve (e.g., 'tasks', 'projects', 'tags').
158 
1599. `ticktick_get_tasks_from_project`
160   * Retrieves all uncompleted tasks from a specific project
161   * Inputs:
162     * `project_id` (string): The ID of the project.
163 
16410. `ticktick_filter_tasks`
165    * Filters tasks based on various criteria
166    * Inputs:
167      * `filter_criteria` (object): Dictionary with filtering parameters such as:
168        * `status` (string): Task status ('uncompleted' or 'completed').
169        * `project_id` (string, optional): Project ID to filter tasks by.
170        * `tag_label` (string, optional): Tag name to filter tasks by.
171        * `priority` (integer, optional): Priority level.
172        * `due_start_date` (string, optional): ISO format start date for due date filter.
173        * `due_end_date` (string, optional): ISO format end date for due date filter.
174        * `completion_start_date` (string, optional): Start date for completion date filter.
175        * `completion_end_date` (string, optional): End date for completion date filter.
176        * `sort_by_priority` (boolean, optional): Sort results by priority.
177        * `tz` (string, optional): Timezone for date interpretation.
178 
179### Helper Tools
180 
18111. `ticktick_convert_datetime_to_ticktick_format`
182    * Converts ISO 8601 date/time string to TickTick API format
183    * Inputs:
184      * `datetime_iso_string` (string): The date/time string in ISO 8601 format.
185      * `tz` (string): IANA timezone name to interpret the date/time.
186 
187## 🤖 Sample agent prompt
188 
189```
190## Persona: Daily Stand-up Agent
191 
192- **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
193- **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks
194 
195---
196 
197## Core Features & Workflow
198 
1991. **Fetch Current Time** 
200 - Retrieve current time using `time mcp`.
201 
2022. **Session Start & Data Loading** 
203 - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
204 - Call TickTick MCP API to fetch all tasks due **today**. 
205 - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").
206 
2073. **Daily Briefing**
208 Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:
209 
210 **Tasks Due Today:**
211 - Task Name 1
212 - Task Name 2
213 …
214 
215 **Overdue Tasks:**
216 - Task Name 3
217 - Task Name 4
218 …
219 
2204. **Select Key Task** 
221 > "Which of these tasks would you like to focus on first or must complete today? 
222 > Or is there another important task you'd like to add?"
223 
2245. **Task Breakdown (Subtask Creation)** 
225 - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
226 - Example (if "Write project report" is selected):
227  1. Draft outline & table of contents (10 min) 
228  2. Gather & analyze data (30 min) 
229  3. Write section drafts (1 h) 
230  4. Review & revise draft (30 min) 
231  5. Final submission (10 min)
232 
2336. **Confirm & Add Subtasks** 
234 - Ask the user to confirm or adjust the suggested subtasks: 
235  > "Does this breakdown look good? Any changes?" 
236 - 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]". 
237 mcp.ticktick.addTask({
238  name: "[Main Task] – [Subtask]",
239  parentId: "..."
240 });
241 
2427. **Session Close** 
243 > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"
244 
245---
246 
247## Additional Guidelines
248 
249- **Tone & Manner**: Friendly, proactive, and organized. 
250- **MCP Interface Examples**: 
251 // Fetch today's due tasks
252 mcp.ticktick.getTasks({
253 filter_criteria: {
254  status: "uncompleted",
255  tz: "Asia/Seoul",
256  due_end_date: "2025-04-29"
257 }
258 });
259 
260 // Add a subtask
261 mcp.ticktick.addTask({
262 name: "Project Report – Write Draft",
263 parentId: "task123"
264 });
265- **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
266- **Clarity**: Present task lists and subtask suggestions clearly. 
267- **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.
268 
269```
270 
271## 🤝 Contributing
272 
273Contributions are welcome! Please feel free to open an issue or submit a pull request.
274 
275 
276## 📜 License
277 
278This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
279 
280## 🔗 See Also
281 
282* [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers): The central repository for reference implementations of MCP servers for various tools and platforms.
283* [modelcontextprotocol.io](https://modelcontextprotocol.io/): Official documentation for the Model Context Protocol.
284* [pietrozullo/mcp-use](https://github.com/pietrozullo/mcp-use): A popular Python library for building clients/agents that interact with MCP servers.
285* [lazeroffmichael/ticktick-py](https://lazeroffmichael.github.io/ticktick-py/): The unofficial TickTick API library used by this project to handle authentication and API interactions.
286