# Ticktick Sdk

> A comprehensive async Python library for TickTick with MCP support.

- **Type:** MCP server
- **Install:** `agentstack add mcp-dev-mirzabicer-ticktick-sdk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dev-mirzabicer](https://agentstack.voostack.com/s/dev-mirzabicer)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dev-mirzabicer](https://github.com/dev-mirzabicer)
- **Source:** https://github.com/dev-mirzabicer/ticktick-sdk

## Install

```sh
agentstack add mcp-dev-mirzabicer-ticktick-sdk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://ticktick.com) with [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server support.

Includes full support for [Dida365 (滴答清单)](https://dida365.com) 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](https://github.com/sebpretzer/pyticktick) | [ticktick-py](https://github.com/lazeroffmichael/ticktick-py) | [tickthon](https://github.com/anggelomos/tickthon) | [ticktick-python](https://github.com/glasslion/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

```bash
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](https://developer.ticktick.com/manage)
2. Click **"Create App"**
3. Fill in:
   - **App Name**: e.g., "My TickTick MCP"
   - **Redirect URI**: `http://127.0.0.1:8080/callback`
4. Save your **Client ID** and **Client Secret**

### Step 2: Get OAuth2 Access Token

Run the auth command with your credentials:

```bash
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 \
      ...
```

4. **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)

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

```bash
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`

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

```bash
# 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](https://developer.ticktick.com/manage) and create an app.

#### Step 2: Create Your .env File

Create a `.env` file in your project directory:

```bash
# 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

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

Copy the access token to your `.env` file.

#### Step 4: Verify Setup

```python
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

```python
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

```python
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

```python
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dev-mirzabicer-ticktick-sdk
- Seller: https://agentstack.voostack.com/s/dev-mirzabicer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.