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…
Details
- Author
- dev-mirzabicer
- Downloads
- 355
- Categories
- Developer Tools
Jump to
- 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
Install via pip install ticktick-sdk with Python 3.11+. Configure authentication by registering an OAuth2 app on the TickTick Developer Portal and creating a .env file with your client ID, secret, redirect URI, access token, username, and password. Run python scripts/get_oauth_token.py for the token, then verify with python -c .... The MCP server can then be invoked through any MCP-compatible host; the library itself exposes 45 tools for AI assistants.
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.
