TickTick API Client & MCP Server

MCP Python License: MIT

A Python client library for TickTick with two ways to use it:

MCP Server - Use TickTick with Claude Desktop through natural conversation
Python CLI/Library - Programmatic access for automation and scripting

Choose Your Adventure

🤖 Want to use TickTick with Claude Desktop?

→

Manage tasks through conversation:

You: "Add a high priority task to call mom tomorrow" Claude: ✓ Created task: Call mom (Priority: High, Due: tomorrow)

💻 Want CLI tools or Python automation?

→ Continue reading below

Use command-line tools or build custom scripts:

python add_task.py "Buy groceries" --priority 5 --due today

Overview

This project provides three approaches to interact with TickTick:

MCP Server (ticktick_mcp_server.py) - Model Context Protocol server for Claude Desktop
REST API Client (ticktick_rest_api.py) - Direct REST API implementation for automation
OAuth Client (ticktick_setup.py) - Uses the ticktick-py library (currently broken)

Features

MCP Server:

Natural language task creation and management
Conversational interface through Claude Desktop
Real-time task status and project overview
Fuzzy search for tasks and projects

Python Client:

Create and manage TickTick projects (lists)
Create recurring tasks with RRULE syntax
Set task priorities, due dates, and reminders
OAuth2 authentication with token caching
REST API implementation for advanced use cases
Command-line tools for quick task addition

Quick Start (5 Minutes)

1. Install Dependencies

pip install -r requirements.txt

2. Configure Credentials

Copy .env.example to .env and add your credentials:

cp .env.example .env

Edit .env:

TICKTICK_USERNAME=your-email@example.com TICKTICK_PASSWORD=your-password

For REST API usage, also add:

TICKTICK_CLIENT_ID=your-client-id-here TICKTICK_CLIENT_SECRET=your-client-secret-here TICKTICK_REDIRECT_URI=http://127.0.0.1:8080

Get API credentials:

Go to https://developer.ticktick.com/manage
Click "+ App Name" and create an app
Set redirect URI to: http://127.0.0.1:8080
Copy your Client ID and Client Secret

3. Test Authentication

# Test OAuth client python test_ticktick_auth.py # Or test REST API python ticktick_rest_api.py

Usage Examples

Quick Start: Add Individual Tasks (Recommended)

The easiest way to add tasks is using the add_task.py script:

# Simple task python add_task.py "Buy groceries" # Task with description python add_task.py "Exercise" --content "30 min walk in the park" # High priority task in a specific project python add_task.py "Morning workout" --project Health --priority 5 # Task with due date python add_task.py "Doctor appointment" --due "2025-11-20" --priority 5 # Task due today or tomorrow python add_task.py "Call Nicole" --due today --priority 3 python add_task.py "Weekly check-in" --due tomorrow --project Marriage # Full example with everything python add_task.py "Weekly check-in" \ --project Marriage \ --content "Review the week together" \ --priority 5 \ --due tomorrow

Adding long descriptions:

# Multi-line description using heredoc python add_task.py "Sunday Marriage Check-in" --project Marriage --priority 5 --content "$(cat <<'EOF' 6 Questions Framework: 1. Connection Score (1-10) 2. What Made Me Feel Loved 3. What Hurt or Frustrated Me 4. Body/Aging Struggle This Week 5. Intimacy Check 6. What I Need Next Week Process: - Both write answers (10 min) - Share and listen (15 min) - Connect physically (5 min) EOF )"

Priority levels:

5 = High (red)
3 = Medium (yellow)
1 = Low (blue)
0 = None (no color)

REST API Client (For Full System Setup)

⚠️ Important: Use ticktick_rest_api.py instead of ticktick_setup.py. The OAuth client (ticktick-py library) is currently broken and re-authenticates on every run.

# Create entire Health & Marriage tracking system python ticktick_rest_api.py --setup # View current status python ticktick_rest_api.py --status # Test authentication python ticktick_rest_api.py --auth

Programmatic Usage (Advanced)

from ticktick_rest_api import TickTickClient import os # Initialize client client = TickTickClient( client_id=os.getenv('TICKTICK_CLIENT_ID'), client_secret=os.getenv('TICKTICK_CLIENT_SECRET'), redirect_uri='http://127.0.0.1:8080' ) # Create a task task = client.create_task( title="Important Task", content="Task description here", priority=5, dueDate="2024-12-31T23:59:59+0000", timeZone="America/Los_Angeles" ) # Get all tasks tasks = client.get_tasks() # Get all projects projects = client.get_projects()

Project Structure

ticktick-api-client/ ├── README.md # This file - Main documentation ├── MCP_README.md # 🤖 MCP Server setup and usage ├── EXAMPLES.md # 💬 Real-world MCP usage examples ├── CLAUDE.md # Guide for Claude Code ├── ticktick_mcp_server.py # 🆕 MCP server implementation ├── add_task.py # ⭐ Quick script to add individual tasks ├── ticktick_rest_api.py # ✅ REST API client (WORKING) ├── ticktick_setup.py # ❌ OAuth client (BROKEN - use REST API instead) ├── test_ticktick_auth.py # Authentication testing ├── requirements.txt # Python dependencies ├── pyproject.toml # Package metadata ├── LICENSE # MIT License ├── .env.example # Environment variables template └── .gitignore # Git ignore rules

Documentation

MCP Server (Claude Desktop)

MCP_README.md - 🤖 MCP Server Setup - Use TickTick with Claude Desktop
EXAMPLES.md - 💬 Usage Examples - Real conversations with Claude

Python CLI/Library

GETTING-STARTED.md - ⭐ START HERE - Complete setup guide for new users
ADDING-TASKS-CLI.md - ⭐ Quick Reference - Add tasks using ~/bin/tt command
TICKTICK-QUICKSTART.md - Get started in 5 minutes
TICKTICK-SETUP.md - Complete setup guide with examples
CLAUDE.md - Technical architecture and development guide

API Reference

Task Creation

# Daily recurring task repeat="RRULE:FREQ=DAILY;INTERVAL=1" # Weekly on Sunday repeat="RRULE:FREQ=WEEKLY;BYDAY=SU" # Every 3 days repeat="RRULE:FREQ=DAILY;INTERVAL=3" # Weekdays only (Mon-Fri) repeat="RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"

Priority Levels

5 = High (red)
3 = Medium (yellow)
1 = Low (blue)
0 = None (no color)

Troubleshooting

Authentication Failed

ValueError: TICKTICK_USERNAME and TICKTICK_PASSWORD must be set

Fix: Add credentials to .env file

Tasks Not Appearing

Check TickTick web/app to verify projects were created
Run authentication test: python test_ticktick_auth.py
Delete projects in TickTick and re-run setup

Token Expired

Tokens are cached in .ticktick-token.json and .token-oauth. If authentication fails:

rm .ticktick-token.json .token-oauth python test_ticktick_auth.py

Use Cases

This library can be used for:

Personal task management automation
Habit tracking systems
Project management integrations
Team workflow automation
Custom productivity tools
Health and wellness tracking
Recurring reminder systems

Security

Never commit .env file to version control
Token files (.ticktick-token.json, .token-oauth) are auto-ignored
OAuth tokens are cached locally for security
Credentials are only used for initial authentication

Dependencies

ticktick-py - Official TickTick Python SDK
requests - HTTP library for REST API
python-dotenv - Environment variable management

Contributing

This is a reference implementation. Feel free to:

Fork and customize for your needs
Add new features
Improve error handling
Extend REST API coverage

License

MIT License - Use freely in your projects

Links

Built for automation enthusiasts who want programmatic control over their TickTick workflows.

TickTick MCP Server