TickTick

You can integrate TickTick with your MCP-enabled assistants and tools to manage tasks with powerful filtering, retrieval, and modification capabilities. This TickTick MCP Server acts as a bridge between TickTick’s API and MCP clients, letting you create, read, update, delete, and organize tasks, projects, and tags through concise MCP commands.

How to use

Set up your MCP client to connect to the TickTick MCP Server. You will use a local or remote command configuration that launches the MCP adapter and exposes TickTick capabilities to your AI assistants and automation workflows.

How to install

Prerequisites: Python 3.10 or newer.

1. Prepare TickTick API credentials by registering an application and obtaining a Client ID, Client Secret, and Redirect URI. You will also need your TickTick login email and password. Keep these values secure.

2. Create an environment file with your TickTick credentials and OAuth settings. Save this as .env in the designated directory (default: ~/.config/ticktick-mcp/.env). The content should include the following keys and placeholder values.

TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret
TICKTICK_REDIRECT_URI=your_redirect_uri
TICKTICK_USERNAME=your_ticktick_email
TICKTICK_PASSWORD=your_ticktick_password

3. On first run, authorize the application when prompted. A browser window opens or a URL is printed; log in to TickTick and grant permissions. Copy the redirected URL (including code=) back to the terminal. A token cache file will be created for future runs.

4. Start the MCP connection using the provided command configuration. The TickTick MCP Server is designed to be launched via an MCP client configuration that points to the stdio adapter.

5. Connect your MCP client (for example Claude Desktop or VS Code Agent Mode) to the TickTick MCP Server using the following setup.

Running the server via MCP client

{
  "mcpServers": {
    "ticktick": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jen6/ticktick-mcp.git",
        "ticktick-mcp"
      ]
    }
  }
}

Tools and capabilities

The TickTick MCP Server exposes actions to manage tasks, subtasks, and retrieval operations. You can create, update, delete, complete, and move tasks, create subtasks, fetch tasks by various filters, and access project and tag information. A helper tool converts datetime strings to TickTick’s required format.

Tools available from TickTick MCP Server

1) ticktick_create_task
   Creates a new TickTick task with fields like title, projectId, content, dueDate, priority, reminders, and subtasks.

2) ticktick_update_task
   Updates an existing task using a task Object, including the task id.

3) ticktick_delete_tasks
   Deletes one or more tasks by id(s).

4) ticktick_complete_task
   Marks a task as complete by id.

5) ticktick_move_task
   Moves a task to a new project by task id and destination project id.

6) ticktick_make_subtask
   Sets a parent task for a given child task, creating a subtask relationship.

7) ticktick_get_by_id
   Retrieves a specific object (task, project, etc.) by its id.

8) ticktick_get_all
   Retrieves all objects of a specified type (tasks, projects, tags).

9) ticktick_get_tasks_from_project
   Gets all uncompleted tasks from a specific project.

10) ticktick_filter_tasks
    Filters tasks by status, project, tag, priority, due/completion date ranges, and timezone.

11) ticktick_convert_datetime_to_ticktick_format
    Converts ISO 8601 date/time to TickTick's internal format.

Notes and troubleshooting

If you encounter authentication issues, re-run the OAuth flow to refresh the access token. Ensure the Redirect URI exactly matches what you configured. If you see errors when calling MCP endpoints, verify that the environment variables are loaded correctly and that the TickTick account has the necessary permissions.

Security and maintenance

Keep API credentials secure. Rotate Client Secret periodically and update the environment file accordingly. Do not commit credentials to version control. Regularly re-authenticate if token expiration occurs.

Available tools

ticktick_create_task

Creates a new TickTick task with fields such as title, projectId, content, due date, reminders, and subtasks.

ticktick_update_task

Updates an existing TickTick task identified by its id with new properties.

ticktick_delete_tasks

Deletes one or more tasks by their IDs.

ticktick_complete_task

Marks a specific task as complete.

ticktick_move_task

Moves a task to a different project by task id and destination project id.

ticktick_make_subtask

Creates a parent-child relationship between tasks, making one a subtask of another.

ticktick_get_by_id

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

ticktick_get_all

Retrieves all objects of a given type (tasks, projects, tags).

ticktick_get_tasks_from_project

Retrieves all uncompleted tasks from a specified project.

ticktick_filter_tasks

Filters tasks based on criteria like status, project, tag, priority, and date ranges.

ticktick_convert_datetime_to_ticktick_format

Converts ISO 8601 date/time strings to TickTick's required format.