TickTick API Client & MCP Server

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

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

Choose Your Adventure

🤖 Want to use TickTick with Claude Desktop?

→ MCP Server Setup

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:

1. MCP Server (ticktick_mcp_server.py) - Model Context Protocol server for Claude Desktop
2. REST API Client (ticktick_rest_api.py) - Direct REST API implementation for automation
3. 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:

1. Go to https://developer.ticktick.com/manage
2. Click "+ App Name" and create an app
3. Set redirect URI to: http://127.0.0.1:8080
4. 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

• TickTick Developer Portal
• TickTick API Documentation
• ticktick-py GitHub

---

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