Ticktick Sdk

ticktick-sdk: A TickTick MCP Server & Full Python SDK

[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://pepy.tech/projects/ticktick-sdk)

A comprehensive async Python SDK for TickTick with MCP (Model Context Protocol) server support.

Includes full support for Dida365 (滴答清单) as well.

Use TickTick programmatically from Python, or let AI assistants manage your tasks.

Table of Contents

• [Features](#features)
• [Why This Library?](#why-this-library)
• [Installation](#installation)
• [MCP Server Setup & Usage](#mcp-server-setup--usage)
• [Step 1: Register Your App](#step-1-register-your-app)
• [Step 2: Get OAuth2 Access Token](#step-2-get-oauth2-access-token)
• [Step 3: Configure Your AI Assistant](#step-3-configure-your-ai-assistant)
• [CLI Reference](#cli-reference)
• [Example Conversations](#example-conversations)
• [Available MCP Tools](#available-mcp-tools-43-total)
• [Python Library Setup & Usage](#python-library-setup--usage)
• [Setup](#setup)
• [Quick Start](#quick-start)
• [Tasks](#tasks)
• [Projects & Folders](#projects--folders)
• [Tags](#tags)
• [Habits](#habits)
• [Focus/Pomodoro](#focuspomodoro)
• [User & Statistics](#user--statistics)
• [Error Handling](#error-handling)
• [Architecture](#architecture)
• [API Reference](#api-reference)
• [TickTick API Quirks](#important-ticktick-api-quirks)
• [Environment Variables](#environment-variables)
• [Running Tests](#running-tests)
• [Troubleshooting](#troubleshooting)
• [Contributing](#contributing)

---

Features

MCP Server

• 43 Tools: Streamlined coverage of TickTick functionality
• Batch Operations: All mutations accept lists (1-100 items) for bulk operations
• AI-Ready: Works with Claude, GPT, and other MCP-compatible assistants
• Dual Output: Markdown for humans, JSON for machines

Python Library

• Full Async Support: Built on httpx for high-performance async operations
• Batch Operations: Create, update, delete, complete up to 100 tasks in a single call
• Complete Task Management: Create, read, update, delete, complete, move, pin tasks
• Kanban Boards: Full column management (create, update, delete, move tasks between columns)
• Project Organization: Projects, folders, kanban boards
• Tag System: Hierarchical tags with colors
• Habit Tracking: Full CRUD for habits with batch check-ins, streaks, and goals
• Focus/Pomodoro: Access focus session data and statistics
• User Analytics: Productivity scores, levels, completion rates

Developer Experience

• Type-Safe: Full Pydantic v2 validation with comprehensive type hints
• Well-Tested: 300+ tests covering both mock and live API interactions
• Documented: Extensive docstrings and examples

---

Why This Library?

The Two-API Problem

TickTick has two different APIs:

| API | Type | What We Use It For | |-----|------|-------------------| | V1 (OAuth2) | Official, documented | Project with all tasks, basic operations | | V2 (Session) | Unofficial, reverse-engineered | Tags, folders, habits, focus, subtasks, and more |

The official V1 API is limited. Most of TickTick's power features (tags, habits, focus tracking) are only available through the undocumented V2 web API. This library combines both, routing each operation to the appropriate API automatically.

Compared to Other Libraries

Based on analysis of the actual source code of available TickTick Python libraries:

| Feature | ticktick-sdk | pyticktick | ticktick-py | tickthon | ticktick-python | |---------|:------------:|:----------:|:-----------:|:--------:|:---------------:| | I/O Model | Async | Async | Sync | Sync | Sync | | Type System | Pydantic V2 | Pydantic V2 | Dicts | attrs | addict | | MCP Server | Yes | No | No | No | No | | Habits | Full CRUD | No | Basic | Basic | No | | Focus/Pomo | Yes | Yes | Yes | Yes | No | | Unified V1+V2 | Smart Routing | Separate | Both | V2 only | V2 only | | Subtasks | Advanced | Batch | Yes | Basic | Basic | | Tags | Full (merge/rename) | Yes | Yes | Yes | No |

Key Differentiators:

• MCP Server: Only ticktick-sdk provides AI assistant integration via Model Context Protocol
• Unified API Routing: Automatically routes operations to V1 or V2 based on feature requirements
• Full Habit CRUD: Complete habit management including check-ins, streaks, archive/unarchive
• Async-First: Built on httpx for high-performance async operations

---

Installation

pip install ticktick-sdk

Requirements:

• Python 3.11+
• TickTick account (free or Pro)

---

MCP Server Setup & Usage

Use TickTick with AI assistants like Claude through the Model Context Protocol.

Step 1: Register Your App

1. Go to the TickTick Developer Portal
2. Click "Create App"
3. Fill in:

• App Name: e.g., "My TickTick MCP"
• Redirect URI: http://127.0.0.1:8080/callback

1. Save your Client ID and Client Secret

Step 2: Get OAuth2 Access Token

Run the auth command with your credentials:

TICKTICK_CLIENT_ID=your_client_id \
TICKTICK_CLIENT_SECRET=your_client_secret \
ticktick-sdk auth

This will:

1. Open your browser to TickTick's authorization page
2. Authorize the app - Click "Authorize" to grant access
3. Return to terminal - After authorizing, you'll see output like this:

============================================================
  SUCCESS! Here is your access token:
============================================================

a]234abc-5678-90de-f012-34567890abcd

============================================================

NEXT STEPS:

For Claude Code users:
  Run (replace YOUR_* placeholders):
    claude mcp add ticktick \
      -e TICKTICK_CLIENT_ID=YOUR_CLIENT_ID \
      ...

1. Copy this token - You'll need it in the next step

> Note: Sometimes the browser shows an "invalid credentials" error page. Just refresh the page and it should work.

> SSH/Headless Users: Add --manual flag for a text-based flow that doesn't require a browser.

Step 3: Configure Your AI Assistant

Claude Code (Recommended)

claude mcp add ticktick \
  -e TICKTICK_CLIENT_ID=your_client_id \
  -e TICKTICK_CLIENT_SECRET=your_client_secret \
  -e TICKTICK_ACCESS_TOKEN=your_access_token \
  -e TICKTICK_USERNAME=your_email \
  -e TICKTICK_PASSWORD=your_password \
  -- ticktick-sdk

> Note: For TICKTICK_ACCESS_TOKEN, paste the token you copied from Step 2.

Verify it's working:

claude mcp list        # See all configured servers
/mcp                   # Within Claude Code, check server status

Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "ticktick-sdk",
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

Other MCP-Compatible Tools

This server works with any tool that supports the Model Context Protocol, which includes most modern AI assistants and IDEs. The configuration is similar - you just need to provide the command (ticktick-sdk) and the environment variables shown above.

CLI Reference

The ticktick-sdk command provides several subcommands:

| Command | Description | |---------|-------------| | ticktick-sdk | Start the MCP server (default) | | ticktick-sdk server | Start the MCP server (explicit) | | ticktick-sdk server --host HOST | Use specific API host (ticktick.com or dida365.com) | | ticktick-sdk server --enabledModules MODULES | Enable only specific tool modules (comma-separated) | | ticktick-sdk server --enabledTools TOOLS | Enable only specific tools (comma-separated) | | ticktick-sdk auth | Get OAuth2 access token (opens browser) | | ticktick-sdk auth --manual | Get OAuth2 access token (SSH-friendly) | | ticktick-sdk --version | Show version information | | ticktick-sdk --help | Show help message |

Tool Filtering (reduces context window usage for AI assistants):

# Enable only task and project tools
ticktick-sdk server --enabledModules tasks,projects

# Enable specific tools only
ticktick-sdk server --enabledTools ticktick_create_tasks,ticktick_list_tasks

# Available modules: tasks, projects, folders, columns, tags, habits, user, focus

Example Conversations

Once configured, you can ask Claude things like:

• "What tasks do I have due today?"
• "Create a task to call John tomorrow at 2pm"
• "Show me my high priority tasks"
• "Mark the grocery shopping task as complete"
• "What's my current streak for the Exercise habit?"
• "Check in my meditation habit for today"
• "Create a new habit to drink 8 glasses of water daily"

Available MCP Tools (43 Total)

All mutation tools accept lists for batch operations (1-100 items).

Task Tools (Batch-Capable)

| Tool | Description | |------|-------------| | ticktick_create_tasks | Create 1-50 tasks with titles, dates, tags, etc. | | ticktick_get_task | Get task details by ID | | ticktick_list_tasks | List tasks (active/completed/abandoned/deleted via status filter) | | ticktick_update_tasks | Update 1-100 tasks (includes column assignment) | | ticktick_complete_tasks | Complete 1-100 tasks | | ticktick_delete_tasks | Delete 1-100 tasks (moves to trash) | | ticktick_move_tasks | Move 1-50 tasks between projects | | ticktick_set_task_parents | Set parent-child relationships for 1-50 tasks | | ticktick_unparent_tasks | Remove parent relationships from 1-50 tasks | | ticktick_search_tasks | Search tasks by text | | ticktick_pin_tasks | Pin or unpin 1-100 tasks |

Project Tools

| Tool | Description | |------|-------------| | ticktick_list_projects | List all projects | | ticktick_get_project | Get project details with tasks | | ticktick_create_project | Create a new project | | ticktick_update_project | Update project properties | | ticktick_delete_project | Delete a project |

Folder Tools

| Tool | Description | |------|-------------| | ticktick_list_folders | List all folders | | ticktick_create_folder | Create a folder | | ticktick_rename_folder | Rename a folder | | ticktick_delete_folder | Delete a folder |

Kanban Column Tools

| Tool | Description | |------|-------------| | ticktick_list_columns | List columns for a kanban project | | ticktick_create_column | Create a kanban column | | ticktick_update_column | Update column name or order | | ticktick_delete_column | Delete a kanban column |

Tag Tools

| Tool | Description | |------|-------------| | ticktick_list_tags | List all tags | | ticktick_create_tag | Create a tag with color | | ticktick_update_tag | Update tag properties (includes rename via label) | | ticktick_delete_tag | Delete a tag | | ticktick_merge_tags | Merge two tags |

Habit Tools (Batch-Capable)

| Tool | Description | |------|-------------| | ticktick_habits | List all habits | | ticktick_habit | Get habit details | | ticktick_habit_sections | List sections (morning/afternoon/night) | | ticktick_create_habit | Create a new habit | | ticktick_update_habit | Update habit properties (includes archive/unarchive) | | ticktick_delete_habit | Delete a habit | | ticktick_checkin_habits | Check in 1-50 habits (supports backdating) | | ticktick_habit_checkins | Get check-in history |

User & Analytics Tools

| Tool | Description | |------|-------------| | ticktick_get_profile | Get user profile | | ticktick_get_status | Get account status | | ticktick_get_statistics | Get productivity stats | | ticktick_get_preferences | Get user preferences | | ticktick_focus_heatmap | Get focus heatmap data | | ticktick_focus_by_tag | Get focus time by tag |

---

Python Library Setup & Usage

Use TickTick programmatically in your Python applications.

Setup

Step 1: Register Your App

Same as MCP setup - go to the TickTick Developer Portal and create an app.

Step 2: Create Your .env File

Create a .env file in your project directory:

# V1 API (OAuth2)
TICKTICK_CLIENT_ID=your_client_id_here
TICKTICK_CLIENT_SECRET=your_client_secret_here
TICKTICK_REDIRECT_URI=http://127.0.0.1:8080/callback
TICKTICK_ACCESS_TOKEN=  # Will be filled in Step 3

# V2 API (Session)
TICKTICK_USERNAME=your_ticktick_email@example.com
TICKTICK_PASSWORD=your_ticktick_password

# Optional
TICKTICK_TIMEOUT=30

Step 3: Get OAuth2 Access Token

# Source your .env file first, or export the variables
ticktick-sdk auth

Copy the access token to your .env file.

Step 4: Verify Setup

import asyncio
from ticktick_sdk import TickTickClient

async def test():
    async with TickTickClient.from_settings() as client:
        profile = await client.get_profile()
        print(f'Connected as: {profile.display_name}')

asyncio.run(test())

Quick Start

import asyncio
from ticktick_sdk import TickTickClient

async def main():
    async with TickTickClient.from_settings() as client:
        # Create a task
        task = await client.create_task(
            title="Learn ticktick-sdk",
            tags=["python", "productivity"],
        )
        print(f"Created: {task.title} (ID: {task.id})")

        # List all tasks
        tasks = await client.get_all_tasks()
        print(f"You have {len(tasks)} active tasks")

        # Complete the task
        await client.complete_task(task.id, task.project_id)
        print("Task completed!")

asyncio.run(main())

Tasks

Creating Tasks

from datetime import datetime, timedelta
from ticktick_sdk import TickTickClient

async with TickTickClient.from_settings() as client:
    # Simple task
    task = await client.create_task(title="Buy groceries")

    # Task with due date and priority
    task = await client.create_task(
        title="Submit report",
        due_date=datetime.now() + timedelta(days=1),
        priority="high",  # none, low, medium, high
    )

    # Task with tags and content
    task = await client.create_task(
        title="Review PR #123",
        content="Check for:\n- Code style\n- Tests\n- Documentation",
        tags=["work", "code-review"],
    )

    # Recurring task (MUST include start_date!)
    task = await client.create_task(
        title="Daily standup",
        start_date=datetime(2025, 1, 20, 9, 0),
        recurrence="RRULE:FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR",
    )

    # Task with reminder
    task = await client.create_task(
        title="Meeting with team",
        due_date=datetime(2025, 1, 20, 14, 0),
        reminders=["TRIGGER:-PT15M"],  # 15 minutes before
    )

    # All-day task
    task = await client.create_task(
        title="Project deadline",
        due_date=datetime(2025, 1, 31),
        all_day=True,
    )

Managing Tasks

async with TickTickClient.from_settings() as client:
    # Get a specific task
    task = await client.get_task(task_id="...")

    # Update a task
    task.title = "Updated title"
    task.priority = 5  # high priority
    await client.update_task(task)

    # Complete a task
    await client.complete_task(task_id="...", project_id="...")

    # Delete a task (moves to

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dev-mirzabicer](https://github.com/dev-mirzabicer)
- **Source:** [dev-mirzabicer/ticktick-sdk](https://github.com/dev-mirzabicer/ticktick-sdk)
- **License:** MIT

Install and usage instructions live in the source repository linked above.