Skip to content
Back to search

ticktick-mcp

MCP server that interacts with TickTick (Dida 365) via the TickTick Open API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jacepark12--ticktick-mcp/badge.svg)](/listings/jacepark12--ticktick-mcp)

HTML

<a href="/listings/jacepark12--ticktick-mcp"><img src="/api/listings/jacepark12--ticktick-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. **Clone this repository**:

   git clone https://github.com/jacepark12/ticktick-mcp.git
   cd ticktick-mcp

2. **Install with uv**:

   # Install uv if you don't have it already
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Create a virtual environment
   uv venv

   # Activate the virtual environment
   # On macOS/Linux:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate

   # Install the package
   uv pip install -e .

3. **Authenticate with TickTick**:

   # Run the authentication flow
   uv run -m ticktick_mcp.cli auth

This will: - Ask for your TickTick Client ID and Client Secret - Open a browser window for you to log in to TickTick - Automatically save your access tokens to a `.env` file

4. **Test your configuration**:

   uv run test_server.py

This will verify that your TickTick credentials are working correctly.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 257 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # TickTick MCP Server
  2. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.
  3. ## Features
  4. - 📋 View all your TickTick projects and tasks
  5. - ✏️ Create new projects and tasks through natural language
  6. - 🔄 Update existing task details (title, content, dates, priority)
  7. - ✅ Mark tasks as complete
  8. - 🗑️ Delete tasks and projects
  9. - 🔄 Full integration with TickTick's open API
  10. - 🔌 Seamless integration with Claude and other MCP clients
  11. ## Prerequisites
  12. - Python 3.10 or higher
  13. - [uv](https://github.com/astral-sh/uv) - Fast Python package installer and resolver
  14. - TickTick account with API access
  15. - TickTick API credentials (Client ID, Client Secret, Access Token)
  16. ## Installation
  17. 1. **Clone this repository**:
  18. ```bash
  19. git clone https://github.com/jacepark12/ticktick-mcp.git
  20. cd ticktick-mcp
  21. ```
  22. 2. **Install with uv**:
  23. ```bash
  24. # Install uv if you don't have it already
  25. curl -LsSf https://astral.sh/uv/install.sh | sh
  26. # Create a virtual environment
  27. uv venv
  28. # Activate the virtual environment
  29. # On macOS/Linux:
  30. source .venv/bin/activate
  31. # On Windows:
  32. .venv\Scripts\activate
  33. # Install the package
  34. uv pip install -e .
  35. ```
  36. 3. **Authenticate with TickTick**:
  37. ```bash
  38. # Run the authentication flow
  39. uv run -m ticktick_mcp.cli auth
  40. ```
  41. This will:
  42. - Ask for your TickTick Client ID and Client Secret
  43. - Open a browser window for you to log in to TickTick
  44. - Automatically save your access tokens to a `.env` file
  45. 4. **Test your configuration**:
  46. ```bash
  47. uv run test_server.py
  48. ```
  49. This will verify that your TickTick credentials are working correctly.
  50. ## Authentication with TickTick
  51. This server uses OAuth2 to authenticate with TickTick. The setup process is straightforward:
  52. 1. Register your application at the [TickTick Developer Center](https://developer.ticktick.com/manage)
  53. - Set the redirect URI to `http://localhost:8000/callback`
  54. - Note your Client ID and Client Secret
  55. 2. Run the authentication command:
  56. ```bash
  57. uv run -m ticktick_mcp.cli auth
  58. ```
  59. 3. Follow the prompts to enter your Client ID and Client Secret
  60. 4. A browser window will open for you to authorize the application with your TickTick account
  61. 5. After authorizing, you'll be redirected back to the application, and your access tokens will be automatically saved to the `.env` file
  62. The server handles token refresh automatically, so you won't need to reauthenticate unless you revoke access or delete your `.env` file.
  63. ## Authentication with Dida365
  64. [滴答清单 - Dida365](https://dida365.com/home) is China version of TickTick, and the authentication process is similar to TickTick. Follow these steps to set up Dida365 authentication:
  65. 1. Register your application at the [Dida365 Developer Center](https://developer.dida365.com/manage)
  66. - Set the redirect URI to `http://localhost:8000/callback`
  67. - Note your Client ID and Client Secret
  68. 2. Add environment variables to your `.env` file:
  69. ```env
  70. TICKTICK_BASE_URL='https://api.dida365.com/open/v1'
  71. TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize'
  72. TICKTICK_TOKEN_URL='https://dida365.com/oauth/token'
  73. ```
  74. 3. Follow the same authentication steps as for TickTick
  75. ## Usage with Claude for Desktop
  76. 1. Install [Claude for Desktop](https://claude.ai/download)
  77. 2. Edit your Claude for Desktop configuration file:
  78. **macOS**:
  79. ```bash
  80. nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
  81. ```
  82. **Windows**:
  83. ```bash
  84. notepad %APPDATA%\Claude\claude_desktop_config.json
  85. ```
  86. 3. Add the TickTick MCP server configuration, using absolute paths:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "ticktick": {
  91. "command": "<absolute path to uv>",
  92. "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
  93. }
  94. }
  95. }
  96. ```
  97. 4. Restart Claude for Desktop
  98. Once connected, you'll see the TickTick MCP server tools available in Claude, indicated by the 🔨 (tools) icon.
  99. ## Available MCP Tools
  100. | Tool | Description | Parameters |
  101. |------|-------------|------------|
  102. | `get_projects` | List all your TickTick projects | None |
  103. | `get_project` | Get details about a specific project | `project_id` |
  104. | `get_project_tasks` | List all tasks in a project | `project_id` |
  105. | `get_task` | Get details about a specific task | `project_id`, `task_id` |
  106. | `create_task` | Create a new task | `title`, `project_id`, `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |
  107. | `update_task` | Update an existing task | `task_id`, `project_id`, `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |
  108. | `complete_task` | Mark a task as complete | `project_id`, `task_id` |
  109. | `delete_task` | Delete a task | `project_id`, `task_id` |
  110. | `create_project` | Create a new project | `name`, `color` (optional), `view_mode` (optional) |
  111. | `delete_project` | Delete a project | `project_id` |
  112. ## Task-specific MCP Tools
  113. ### Task Retrieval & Search
  114. | Tool | Description | Parameters |
  115. |------|-------------|------------|
  116. | `get_all_tasks` | Get all tasks from all projects | None |
  117. | `get_tasks_by_priority` | Get tasks filtered by priority level | `priority_id` (0: None, 1: Low, 3: Medium, 5: High) |
  118. | `search_tasks` | Search tasks by title, content, or subtasks | `search_term` |
  119. ### Date-Based Task Retrieval
  120. | Tool | Description | Parameters |
  121. |------|-------------|------------|
  122. | `get_tasks_due_today` | Get all tasks due today | None |
  123. | `get_tasks_due_tomorrow` | Get all tasks due tomorrow | None |
  124. | `get_tasks_due_in_days` | Get tasks due in exactly X days | `days` (0 = today, 1 = tomorrow, etc.) |
  125. | `get_tasks_due_this_week` | Get tasks due within the next 7 days | None |
  126. | `get_overdue_tasks` | Get all overdue tasks | None |
  127. ### Getting Things Done (GTD) Framework
  128. | Tool | Description | Parameters |
  129. |------|-------------|------------|
  130. | `get_engaged_tasks` | Get "engaged" tasks (high priority or overdue) | None |
  131. | `get_next_tasks` | Get "next" tasks (medium priority or due tomorrow) | None |
  132. | `batch_create_tasks` | Create multiple tasks at once | `tasks` (list of task dictionaries) |
  133. ## Example Prompts for Claude
  134. Here are some example prompts to use with Claude after connecting the TickTick MCP server:
  135. ### General
  136. - "Show me all my TickTick projects"
  137. - "Create a new task called 'Finish MCP server documentation' in my work project with high priority"
  138. - "List all tasks in my personal project"
  139. - "Mark the task 'Buy groceries' as complete"
  140. - "Create a new project called 'Vacation Planning' with a blue color"
  141. - "When is my next deadline in TickTick?"
  142. ### Task Filtering Queries
  143. - "What tasks do I have due today?"
  144. - "Show me everything that's overdue"
  145. - "Show me all tasks due this week"
  146. - "Search for tasks about 'project alpha'"
  147. - "Show me all tasks with 'client' in the title or description"
  148. - "Show me all my high priority tasks"
  149. ### GTD Workflow
  150. Following David Allen's "Getting Things Done" framework, manage an Engaged and Next actions.
  151. - Engaged will retrieve tasks of high priority, due today or overdue.
  152. - Next will retrieve medium priority or due tomorrow.
  153. - Break down complex actions into smaller actions with batch_creation
  154. For example:
  155. - "Time block the rest of my day from 2-8pm with items from my engaged list"
  156. - "Walk me through my next actions and help my identify what I should focus on tomorrow?"
  157. - "Break down this project into 5 smaller actionable tasks"
  158. ## Development
  159. ### Project Structure
  160. ```
  161. ticktick-mcp/
  162. ├── .env.template # Template for environment variables
  163. ├── README.md # Project documentation
  164. ├── requirements.txt # Project dependencies
  165. ├── setup.py # Package setup file
  166. ├── test_server.py # Test script for server configuration
  167. └── ticktick_mcp/ # Main package
  168. ├── __init__.py # Package initialization
  169. ├── authenticate.py # OAuth authentication utility
  170. ├── cli.py # Command-line interface
  171. └── src/ # Source code
  172. ├── __init__.py # Module initialization
  173. ├── auth.py # OAuth authentication implementation
  174. ├── server.py # MCP server implementation
  175. └── ticktick_client.py # TickTick API client
  176. ```
  177. ### Authentication Flow
  178. The project implements a complete OAuth 2.0 flow for TickTick:
  179. 1. **Initial Setup**: User provides their TickTick API Client ID and Secret
  180. 2. **Browser Authorization**: User is redirected to TickTick to grant access
  181. 3. **Token Reception**: A local server receives the OAuth callback with the authorization code
  182. 4. **Token Exchange**: The code is exchanged for access and refresh tokens
  183. 5. **Token Storage**: Tokens are securely stored in the local `.env` file
  184. 6. **Token Refresh**: The client automatically refreshes the access token when it expires
  185. This simplifies the user experience by handling the entire OAuth flow programmatically.
  186. ### Contributing
  187. Contributions are welcome! Please feel free to submit a Pull Request.
  188. 1. Fork the repository
  189. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  190. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  191. 4. Push to the branch (`git push origin feature/amazing-feature`)
  192. 5. Open a Pull Request
  193. ## License
  194. This project is licensed under the MIT License - see the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.