TickTick MCP Server

# TickTick MCP Server - Usage Examples This guide shows real-world examples of using the TickTick MCP server with Claude Desktop. ## Basic Task Creation ### Simple Task **You:** ``` Add a task to buy milk ``` **Claude response:** ``` ✓ Created task: Buy milk ID: 67890abc Priority: None ``` ### Task with Priority **You:** ``` Create a high priority task to finish the quarterly report by Friday ``` **Claude response:** ``` ✓ Created task: Finish the quarterly report ID: 12345def Priority: High Due: 2025-11-22T09:00:00 ``` ### Task with Description **You:** ``` Add a task called "Plan vacation" with these details: - Research destinations - Check flight prices - Ask for time off ``` **Claude response:** ``` ✓ Created task: Plan vacation ID: abcdef123 Priority: None Description added: - Research destinations - Check flight prices - Ask for time off ``` ## Project Management ### Create a Project **You:** ``` Create a new project called "Home Renovation" with a green color ``` **Claude response:** ``` ✓ Created project: Home Renovation ID: proj_456 Color: #4CAF50 ``` ### Add Task to Specific Project **You:** ``` Add a task to the Health project: "Go for a 30-minute run" ``` **Claude response:** ``` ✓ Created task: Go for a 30-minute run ID: task789 Priority: None Project: Health ``` ### List All Projects **You:** ``` Show me all my projects ``` **Claude response:** ``` Found 5 project(s): • Marriage ID: 607abc123 Color: #E91E63 • Health ID: 607def456 Color: #4CAF50 • Milestones ID: 607ghi789 Color: #FF9800 • Work ID: 607jkl012 Color: #2196F3 • Personal ID: 607mno345 Color: #9C27B0 ``` ## Viewing Tasks ### List All Tasks **You:** ``` What tasks do I have? ``` **Claude response:** ``` Found 10 task(s): ○ Buy milk Project: Inbox Priority: Low ○ Finish the quarterly report Project: Work Due: 2025-11-22T09:00:00 Priority: High ○ Go for a 30-minute run Project: Health Due: 2025-11-17T07:00:00 Priority: Medium ... ``` ### List Tasks by Project **You:** ``` Show me all tasks in my Health project ``` **Claude response:** ``` Found 7 task(s): ○ Monday: 30 min Strength/Stretch Project: Health Due: 2025-11-18T07:00:00 Priority: High ○ Wednesday: Cycling 45 min Project: Health Due: 2025-11-20T07:00:00 Priority: High ○ Go for a 30-minute run Project: Health Due: 2025-11-17T07:00:00 Priority: Medium ``` ### Get Task Details **You:** ``` Show me details for "Finish the quarterly report" ``` **Claude response:** ``` Task: Finish the quarterly report ID: 12345def Status: Active Project: Work Description: - Compile Q4 metrics - Write executive summary - Create slides for presentation Priority: High Due Date: 2025-11-22T09:00:00 ``` ## Completing Tasks ### Complete a Task **You:** ``` Mark "Buy milk" as complete ``` **Claude response:** ``` ✓ Completed task: Buy milk ``` ### Complete with Fuzzy Matching **You:** ``` I finished the quarterly report, mark it done ``` **Claude response:** ``` ✓ Completed task: Finish the quarterly report ``` ### Multiple Matches **You:** ``` Complete the cycling task ``` **Claude response:** ``` Multiple tasks found matching 'cycling': - Wednesday: Cycling 45 min - Saturday: Cycling 45 min Please be more specific. ``` **You:** ``` Complete "Wednesday: Cycling 45 min" ``` **Claude response:** ``` ✓ Completed task: Wednesday: Cycling 45 min ``` ## Status Overview ### Check Current Status **You:** ``` What's my TickTick status? ``` **Claude uses the `ticktick://status` resource:** ``` TickTick Status Overview ======================================== Total Tasks: 23 Active: 18 Completed: 5 Projects (5): • Marriage: 4 tasks • Health: 7 tasks • Milestones: 3 tasks • Work: 6 tasks • Personal: 3 tasks ``` ## Complex Workflows ### Planning a Week **You:** ``` Help me plan my week. I need to: 1. Exercise Monday, Wednesday, Friday 2. Have a team meeting on Tuesday 3. Finish the project proposal by Thursday 4. Review budget on Friday All should be in my Work project ``` **Claude adds all tasks:** ``` I'll create those tasks for you: ✓ Created task: Exercise Project: Work Due: Monday 7:00 AM Priority: Medium ✓ Created task: Exercise Project: Work Due: Wednesday 7:00 AM Priority: Medium ✓ Created task: Exercise Project: Work Due: Friday 7:00 AM Priority: Medium ✓ Created task: Team meeting Project: Work Due: Tuesday 10:00 AM Priority: High ✓ Created task: Finish project proposal Project: Work Due: Thursday 5:00 PM Priority: High ✓ Created task: Review budget Project: Work Due: Friday 2:00 PM Priority: Medium All tasks created in your Work project! ``` ### Weekly Review **You:** ``` Show me what I completed this week in my Health project ``` **Claude filters and shows:** ``` Found 5 completed task(s): ✓ Monday: 30 min Strength/Stretch Project: Health Completed: 2025-11-11 ✓ Wednesday: Cycling 45 min Project: Health Completed: 2025-11-13 ✓ Thursday: 30 min Strength/Stretch Project: Health Completed: 2025-11-14 ✓ Saturday: Cycling 45 min Project: Health Completed: 2025-11-16 ✓ Sunday: Weekly Health Check-in Project: Health Completed: 2025-11-17 ``` ## Advanced Features ### Using Due Date Keywords **You:** ``` Add a task to call the dentist tomorrow ``` **Claude:** ``` ✓ Created task: Call the dentist ID: xyz789 Priority: None Due: 2025-11-17T09:00:00 ``` **You:** ``` Remind me to take out the trash today ``` **Claude:** ``` ✓ Created task: Take out the trash ID: abc123 Priority: None Due: 2025-11-16T09:00:00 ``` ### Priority Levels **You:** ``` Create a low priority task to organize my desk ``` **Claude:** ``` ✓ Created task: Organize my desk ID: desk001 Priority: Low ``` Priorities: - "high priority" → Priority 5 (red) - "medium priority" → Priority 3 (yellow) - "low priority" → Priority 1 (blue) - No mention → Priority 0 (none) ## Tips & Tricks ### 1. Natural Language Works You don't need exact syntax. These all work: ``` "Add a task..." "Create a new task..." "Remind me to..." "I need to..." "Put this on my list..." ``` ### 2. Fuzzy Project Matching You don't need exact project names: ``` "Add to health..." → Matches "Health" project "Add to marriage..." → Matches "Marriage" project "Add to work..." → Matches "Work" project ``` ### 3. Batch Operations Ask Claude to do multiple things at once: ``` "Show me my Health tasks, then mark the Monday strength task as complete" ``` ### 4. Context Awareness Claude remembers context within a conversation: ``` You: "Show me my Health tasks" Claude: [lists tasks] You: "Mark the first one as complete" Claude: [completes the first task from the previous list] ``` ### 5. Get Creative Combine MCP tools with Claude's intelligence: ``` You: "I have a big presentation next week. Help me break it down into tasks." Claude: I'll help you break that down into manageable tasks: 1. Research and outline (Monday) 2. Create slides (Tuesday-Wednesday) 3. Prepare speaker notes (Thursday) 4. Practice run-through (Friday) 5. Final review (Day before) Should I create these as tasks in your Work project? ``` ## Limitations ### What Works - Creating tasks with title, description, priority, due date - Listing and filtering tasks - Completing tasks - Managing projects - Viewing status ### What Doesn't Work Yet - Recurring tasks (RRULE format not supported via MCP yet) - Tags and labels - Reminders - Subtasks/checklists - Editing existing tasks - Deleting tasks - Time tracking ### Workarounds For features not in MCP, use the CLI: ```bash # Add recurring task via CLI python add_task.py "Weekly review" \ --content "Review progress" \ --project Health \ --repeat "RRULE:FREQ=WEEKLY;BYDAY=SU" ``` ## Troubleshooting ### Task Not Created Check if Claude shows an error. Common issues: - Project name doesn't exist (create it first) - Invalid date format - Authentication expired (re-run `python ticktick_rest_api.py --auth`) ### Can't Find Task Try being more specific: ``` Instead of: "Complete exercise" Try: "Complete Monday: 30 min Strength/Stretch" ``` ### MCP Server Not Responding Restart Claude Desktop and check the config: ```bash cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` ## More Examples? Check out the `test_scenarios.md` file for edge cases and advanced usage, or just experiment with Claude!