dev-mirzabicer/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
- Why This Library?
- Installation
- MCP Server Setup & Usage
- Step 1: Register Your App
- Step 2: Get OAuth2 Access Token
- Step 3: Configure Your AI Assistant
- CLI Reference
- Example Conversations
- Available MCP Tools
- Python Library Setup & Usage
- Setup
- Quick Start
- Tasks
- Projects & Folders
- Tags
- Habits
- Focus/Pomodoro
- User & Statistics
- Error Handling
- Architecture
- API Reference
- TickTick API Quirks
- Environment Variables
- Running Tests
- Troubleshooting
- 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
**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
4. Save your **Client ID** and **Client Secret**