Ticktick Mcp
About
Ticktick Mcp is an MCP (Model Context Protocol) server built on the ticktick-sdk Python library that enables AI assistants like Claude and GPT to manage TickTick tasks programmatically. It provides 45 tools covering task management, project organization, habits, focus/pomodoro…
Explore
- 45 MCP tools covering all TickTick features
- Dual output: Markdown for humans, JSON for machines
- Async-first with full Pydantic v2 validation
- Unified routing to V1 (OAuth2) and V2 (session) APIs
- Full habit CRUD with check-ins, streaks, and goals
- Focus/pomodoro session data and statistics
- 300+ tests with comprehensive type hints
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Ticktick McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Python 3.11+
- TickTick account (free or Pro)
- For full functionality: both OAuth2 app registration and account credentials
---
This library requires both V1 and V2 authentication for full functionality.
source .venv/bin/activate
python -c "
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}')
stats = await client.get_statistics()
print(f'Level {stats.level} | Score: {stats.score}')
asyncio.run(test())
"
---
from ticktick_sdk import TickTickClient, Habit
async with TickTickClient.from_settings() as client:
The MCP server enables AI assistants (like Claude) to manage your TickTick tasks through natural language.
ticktick-sdk
| Variable | Required | Description |
|----------|:--------:|-------------|
| TICKTICK_CLIENT_ID | Yes | OAuth2 client ID from developer portal |
| TICKTICK_CLIENT_SECRET | Yes | OAuth2 client secret |
| TICKTICK_ACCESS_TOKEN | Yes | OAuth2 access token (from setup script) |
| TICKTICK_USERNAME | Yes | Your TickTick email |
| TICKTICK_PASSWORD | Yes | Your TickTick password |
| TICKTICK_REDIRECT_URI | No | OAuth2 redirect URI (default: http://127.0.0.1:8080/callback) |
| TICKTICK_TIMEOUT | No | Request timeout in seconds (default: 30) |
| TICKTICK_DEVICE_ID | No | Device ID for V2 API (auto-generated) |
---
- Check your TickTick username (email) and password
- Try logging into ticktick.com to verify credentials
- Ensure there are no extra spaces in your .env file
git clone https://github.com/dev-mirzabicer/ticktick-sdk.git
cd ticktick-sdk
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```
---
ticktick_create_task
Create a new task with title, dates, tags, etc.
ticktick_get_task
Get task details by ID
ticktick_list_tasks
List tasks with optional filters
ticktick_update_task
Update task properties
ticktick_complete_task
Mark task as complete
ticktick_delete_task
Delete a task (moves to trash)
ticktick_move_task
Move task between projects
ticktick_make_subtask
Create parent-child relationship
ticktick_unparent_subtask
Remove parent-child relationship
ticktick_completed_tasks
List recently completed tasks
ticktick_abandoned_tasks
List abandoned ("won't do") tasks
ticktick_deleted_tasks
List deleted tasks (in trash)
ticktick_search_tasks
Search tasks by text
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
ticktick_list_folders
List all folders
ticktick_create_folder
Create a folder
ticktick_rename_folder
Rename a folder
ticktick_delete_folder
Delete a folder
ticktick_list_tags
List all tags
ticktick_create_tag
Create a tag with color
ticktick_update_tag
Update tag color/parent
ticktick_delete_tag
Delete a tag
ticktick_rename_tag
Rename a tag
ticktick_merge_tags
Merge two tags
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
ticktick_delete_habit
Delete a habit
ticktick_checkin_habit
Check in (complete for today)
ticktick_archive_habit
Archive a habit
ticktick_unarchive_habit
Unarchive a habit
ticktick_habit_checkins
Get check-in history
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
| Tool | Description |
|------|-------------|
| ticktick_create_task | Create a new task with title, dates, tags, etc. |
| ticktick_get_task | Get task details by ID |
| ticktick_list_tasks | List tasks with optional filters |
| ticktick_update_task | Update task properties |
| ticktick_complete_task | Mark task as complete |
| ticktick_delete_task | Delete a task (moves to trash) |
| ticktick_move_task | Move task between projects |
| ticktick_make_subtask | Create parent-child relationship |
| ticktick_unparent_subtask | Remove parent-child relationship |
| ticktick_completed_tasks | List recently completed tasks |
| ticktick_abandoned_tasks | List abandoned ("won't do") tasks |
| ticktick_deleted_tasks | List deleted tasks (in trash) |
| ticktick_search_tasks | Search tasks by text |
| 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 |
| 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 |
| Tool | Description |
|------|-------------|
| ticktick_list_tags | List all tags |
| ticktick_create_tag | Create a tag with color |
| ticktick_update_tag | Update tag color/parent |
| ticktick_delete_tag | Delete a tag |
| ticktick_rename_tag | Rename a tag |
| ticktick_merge_tags | Merge two tags |
| 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 |
| ticktick_delete_habit | Delete a habit |
| ticktick_checkin_habit | Check in (complete for today) |
| ticktick_archive_habit | Archive a habit |
| ticktick_unarchive_habit | Unarchive a habit |
| ticktick_habit_checkins | Get check-in history |
| 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 |
---
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"ticktick mcp": {
"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"
}
}
}
}
}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"
}
}
}ticktick-sdk: A TickTick MCP Server & Full Python SDK
A comprehensive async Python SDK for TickTick with MCP (Model Context Protocol) server support.
Use TickTick programmatically from Python, or let AI assistants manage your tasks.
Table of Contents
- Features
- Why This Library?
- Installation
- Authentication Setup
- Usage: Python Library
- Quick Start
- Tasks
- Projects & Folders
- Tags
- Habits
- Focus/Pomodoro
- User & Statistics
- Usage: MCP Server
- Architecture
- API Reference
- TickTick API Quirks
- Running Tests
- Troubleshooting
- Contributing
---
Features
Python Library
- Full Async Support: Built onhttpx for high-performance async operations
- Complete Task Management: Create, read, update, delete, complete, move tasks
- Project Organization: Projects, folders, kanban boards
- Tag System: Hierarchical tags with colors
- Habit Tracking: Full CRUD for habits with check-ins, streaks, and goals
- Focus/Pomodoro: Access focus session data and statistics
- User Analytics: Productivity scores, levels, completion rates
MCP Server
- 45 Tools: Comprehensive coverage of TickTick functionality - AI-Ready: Works with Claude, GPT, and other MCP-compatible assistants - Dual Output: Markdown for humans, JSON for machinesDeveloper 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
From PyPI (Recommended)
pip install ticktick-sdk
From Source (Development)
git clone https://github.com/dev-mirzabicer/ticktick-sdk.git
cd ticktick-sdk
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
Requirements
- Python 3.11+
- TickTick account (free or Pro)
- For full functionality: both OAuth2 app registration and account credentials
---
Authentication Setup
This library requires both V1 and V2 authentication for full functionality.
Step 1: Register Your App (V1 OAuth2)
1. Go to the TickTick Developer Portal
2. Click "Create App"
3. Fill in:
- App Name: e.g., "My TickTick App"
- Redirect URI: http://127.0.0.1:8080/callback
4. Save your Client ID and Client Secret
Step 2: Create Your .env File
cp .env.example .env
Edit .env with your credentials:
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
