Ticktick MCP
MCP (Model Context Protocol) server for TickTick task management. Enables AI assistants like Claude to interact with your TickTick tasks.
Installation
npx ticktick-mcpAsk AI about Ticktick MCP
Powered by Claude Β· Grounded in docs
I know everything about Ticktick MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
TickTick MCP Server
A Model Context Protocol (MCP) server for TickTick task management. This enables AI assistants like Claude to interact with your TickTick tasks.
Features
Project Management
- π Get Projects - List all your TickTick projects/lists
- π Get Project by ID - Get specific project details
- π Get Project with Data - Get project with all tasks and kanban columns
- β Create Project - Create new projects with custom colors and view modes
- βοΈ Update Project - Modify project settings
- ποΈ Delete Project - Remove projects
Task Queries
- β Get Tasks - Retrieve tasks from all projects or a specific one
- π Today's Tasks - Get tasks due today
- β οΈ Overdue Tasks - Get tasks past their due date
- π― Priority Filter - Get high/medium priority tasks
- π·οΈ Filter by Tag - Get tasks with specific tags
- π·οΈ Get All Tags - List all unique tags
Task Management
- β Create Tasks - Add new tasks with title, priority, due date
- β Create with Subtasks - Add tasks with checklist items
- β Add Subtask - Add subtask to existing task
- βοΈ Complete Tasks - Mark tasks as done
- βοΈ Update Tasks - Modify existing tasks
- ποΈ Delete Tasks - Remove tasks
Installation
Option 1: pip install (recommended)
pip install ticktick-mcp
Option 2: From source
git clone https://github.com/ainishanov/ticktick-mcp.git
cd ticktick-mcp
pip install -e .
Setup
1. Get TickTick API Access Token
- Go to TickTick Developer Portal
- Create a new application
- Complete OAuth2 flow to get your access token
- Copy the access token
2. Configure Environment
Create a .env file in the project directory:
cp .env.example .env
Edit .env and add your token:
TICKTICK_ACCESS_TOKEN=your_access_token_here
3. Configure Claude Desktop
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ticktick": {
"command": "python",
"args": ["-m", "ticktick_mcp.server"],
"env": {
"TICKTICK_ACCESS_TOKEN": "your_access_token_here"
}
}
}
}
Or if installed from source:
{
"mcpServers": {
"ticktick": {
"command": "python",
"args": ["-m", "ticktick_mcp.server"],
"cwd": "/path/to/ticktick-mcp/src",
"env": {
"TICKTICK_ACCESS_TOKEN": "your_access_token_here"
}
}
}
}
Claude Code (CLI)
Add to ~/.mcp.json (macOS/Linux) or %USERPROFILE%\.mcp.json (Windows):
{
"mcpServers": {
"ticktick": {
"type": "stdio",
"command": "python",
"args": ["-m", "ticktick_mcp.server"],
"cwd": "/path/to/ticktick-mcp/src",
"env": {
"TICKTICK_ACCESS_TOKEN": "your_access_token_here"
}
}
}
}
4. Restart Claude Desktop
After configuration, restart Claude Desktop to load the MCP server.
Usage Examples
Once configured, you can ask Claude:
- "What tasks do I have today?"
- "Show me all high priority tasks"
- "Create a task 'Review PR #123' with high priority due tomorrow"
- "Mark task ID xxx in project yyy as complete"
- "What projects do I have in TickTick?"
Available Tools
Project Tools
| Tool | Description |
|---|---|
get_projects | List all TickTick projects |
get_project_by_id | Get specific project by ID |
get_project_with_data | Get project with tasks and columns |
create_project | Create a new project |
update_project | Update project settings |
delete_project | Delete a project |
Task Query Tools
| Tool | Description |
|---|---|
get_tasks | Get tasks (all or by project) |
get_today_tasks | Get tasks due today |
get_overdue_tasks | Get tasks past due date |
get_high_priority_tasks | Get high/medium priority tasks |
get_tasks_by_tag | Get tasks by tag |
get_all_tags | List all unique tags |
Task Management Tools
| Tool | Description |
|---|---|
create_task | Create a new task |
create_task_with_subtasks | Create task with checklist |
add_subtask | Add subtask to existing task |
complete_task | Mark task as complete |
update_task | Update task details |
delete_task | Delete a task |
Priority Levels
| Value | Level | Emoji |
|---|---|---|
| 0 | None | βͺ |
| 1 | Low | π΅ |
| 3 | Medium | π‘ |
| 5 | High | π΄ |
Development
# Clone repo
git clone https://github.com/ainishanov/ticktick-mcp.git
cd ticktick-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check .
OAuth2 Token Generation
If you need to generate an access token programmatically, here's a helper script:
import httpx
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
REDIRECT_URI = "http://localhost:8080/callback"
# Step 1: Get authorization URL
auth_url = f"https://ticktick.com/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=tasks:read tasks:write"
print(f"Open this URL in browser:\n{auth_url}")
# Step 2: After redirect, exchange code for token
code = input("Enter the code from redirect URL: ")
response = httpx.post(
"https://ticktick.com/oauth/token",
data={
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"code": code,
"grant_type": "authorization_code",
"redirect_uri": REDIRECT_URI,
},
)
print(response.json())
# Save the access_token to your .env file
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License - see LICENSE file for details.
Acknowledgments
- Model Context Protocol by Anthropic
- TickTick for their API
