TickTick MCP Server

# TickTick API Client & MCP Server [](https://modelcontextprotocol.io) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) 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](MCP_README.md)** 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: ```bash 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 ```bash pip install -r requirements.txt ``` ### 2. Configure Credentials Copy `.env.example` to `.env` and add your credentials: ```bash 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 ```bash # 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: ```bash # 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:** ```bash # 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. ```bash # 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) ```python 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_README.md)** - 🤖 **MCP Server Setup** - Use TickTick with Claude Desktop - **[EXAMPLES.md](EXAMPLES.md)** - 💬 **Usage Examples** - Real conversations with Claude ### Python CLI/Library - **[GETTING-STARTED.md](GETTING-STARTED.md)** - ⭐ **START HERE** - Complete setup guide for new users - **[ADDING-TASKS-CLI.md](ADDING-TASKS-CLI.md)** - ⭐ **Quick Reference** - Add tasks using `~/bin/tt` command - **[TICKTICK-QUICKSTART.md](TICKTICK-QUICKSTART.md)** - Get started in 5 minutes - **[TICKTICK-SETUP.md](TICKTICK-SETUP.md)** - Complete setup guide with examples - **[CLAUDE.md](CLAUDE.md)** - Technical architecture and development guide ## API Reference ### Task Creation ```python # 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 ```bash 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: ```bash 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](https://developer.ticktick.com) - [TickTick API Documentation](https://developer.ticktick.com/api) - [ticktick-py GitHub](https://github.com/lazeroffmichael/ticktick-py) --- **Built for automation enthusiasts who want programmatic control over their TickTick workflows.**