Ticktick

License: MIT Version Python Tools Glama

28 tools. Full CRUD. Smart queries. Multi-condition filters. Batch operations. GTD support. Dida365 compatible.

Connect Claude to your TickTick account and manage your entire task system through natural conversation -- create tasks, search across projects, check what's overdue, batch-create items, and stay organized without ever opening the app.

"What's overdue?" --> Instantly shows all missed deadlines across every project.

---

Why This One?

Feature	This Server	TickTick Official MCP	jacepark12
Tools	28	22	~20
Multi-condition filter	Yes (priority + tag + date + project)	Yes	No
Move task between projects	Yes	Yes	No
Bulk complete	Yes (up to 20)	Yes (up to 20)	No
Batch update	Yes	Yes	No
Completed tasks view	Yes	Yes	No
Cross-project search	Full text search	Yes	Yes
Subtasks	Yes	No	No
GTD focus view	Yes (high priority + due + overdue)	No	Partial
Dida365 support	Yes (configurable base URL)	No	Yes
Async (httpx)	Yes	N/A	No (sync requests)
Pydantic validation	Yes (typed inputs)	N/A	No
MCP annotations	Yes (readOnly, destructive hints)	N/A	No
Self-hosted / open source	Yes	No (hosted service)	Yes
Privacy	100% local, your tokens only	Goes through TickTick servers	100% local

---

Quick Start

Prerequisites

• TickTick account
• Python 3.10+
• Claude Code or Claude Desktop

Step 1 -- Clone and install

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Step 2 -- Register a TickTick developer app

1. Go to developer.ticktick.com
2. Click New App and fill in any name
3. Set OAuth Redirect URL to: http://localhost:8080/callback
4. Copy your Client ID and Client Secret

Step 3 -- Authenticate

TICKTICK_CLIENT_ID=your_id TICKTICK_CLIENT_SECRET=your_secret .venv/bin/python3 setup_auth.py

This opens your browser to authorize the app. Click Allow -- tokens are saved to ~/.ticktick_mcp/tokens.json and refresh automatically.

Step 4 -- Register with Claude Code

claude mcp add ticktick \
  -e TICKTICK_CLIENT_ID=your_id \
  -e TICKTICK_CLIENT_SECRET=your_secret \
  -- /path/to/ticktick-mcp/.venv/bin/python3 /path/to/ticktick-mcp/server.py

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ticktick": {
      "type": "stdio",
      "command": "/path/to/ticktick-mcp/.venv/bin/python3",
      "args": ["/path/to/ticktick-mcp/server.py"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_id",
        "TICKTICK_CLIENT_SECRET": "your_secret"
      }
    }
  }
}

Step 5 -- Add the productivity skill (optional)

mkdir -p ~/.claude/skills/ticktick
cp skills/ticktick/SKILL.md ~/.claude/skills/ticktick/

---

Dida365 Support

For Dida365 (TickTick's Chinese version), set these environment variables:

TICKTICK_BASE_URL=https://api.dida365.com/open/v1
TICKTICK_TOKEN_URL=https://dida365.com/oauth/token

---

Usage Examples

You say	What happens
"Remind me to call the dentist on Friday"	Task created with due date
"Add 'review Q1 report' to Work, high priority"	Task in Work project, priority 5
"What's overdue?"	Shows all overdue tasks across projects
"What should I focus on?"	GTD view: high priority + due today + overdue
"Search for anything about 'budget'"	Full-text search across all projects
"Show me all high priority tasks"	Filters by priority=5 across projects
"What's due this week?"	Tasks due in the next 7 days
"Create tasks: buy milk, call John, submit report"	Batch creates 3 tasks
"Create a project called 'Vacation Planning'"	New project created
"Add subtask 'Buy sunscreen' under the vacation task"	Subtask created
"I finished the dentist task"	Task marked complete
"Delete the old Sprint project"	Project and all tasks deleted

---

MCP Tools Reference

Projects (5 tools)

Tool	Description
ticktick_list_projects	List all projects with IDs, names, colors
ticktick_get_project	Get details of a specific project
ticktick_get_project_with_tasks	Get project details + all undone tasks in one call
ticktick_create_project	Create a new project (name, color, view mode)
ticktick_update_project	Update a project's name, color, or view mode
ticktick_delete_project	Permanently delete a project

Tasks -- Basic CRUD (7 tools)

Tool	Description
ticktick_list_tasks	List all tasks in a specific project
ticktick_create_task	Create a task (title, due date, priority, project, tags)
ticktick_get_task	Get full details of a specific task
ticktick_update_task	Update title, content, dates, or priority
ticktick_complete_task	Mark a task as completed
ticktick_delete_task	Permanently delete a task
ticktick_create_subtask	Create a subtask under a parent task

Tasks -- Smart Queries (7 tools)

Tool	Description
ticktick_get_all_tasks	Get all tasks across all active projects
ticktick_search_tasks	Full-text search across titles, content, subtasks
ticktick_get_tasks_by_priority	Filter by priority (None/Low/Medium/High)
ticktick_get_tasks_due_today	Tasks due today across all projects
ticktick_get_overdue_tasks	All overdue tasks across all projects
ticktick_get_tasks_due_this_week	Tasks due within the next 7 days
ticktick_get_tasks_due_in_days	Tasks due in exactly N days

Tasks -- Batch & Productivity (5 tools)

Tool	Description
ticktick_batch_create_tasks	Create multiple tasks at once
ticktick_batch_update_tasks	Update multiple tasks at once
ticktick_complete_tasks_bulk	Mark up to 20 tasks as completed at once
ticktick_move_task	Move a task from one project to another
ticktick_get_focus_tasks	GTD focus view: high priority + due today + overdue

Tasks -- Advanced Filters (2 tools)

Tool	Description
ticktick_filter_tasks	Multi-condition filter: priority + tag + date range + project + status
ticktick_get_completed_tasks	View completed tasks in a project

User (1 tool)

Tool	Description
ticktick_get_user_preferences	Get user settings (timezone, week start, etc.)

---

Architecture

server.py              # 20 MCP tools, async httpx, Pydantic validation
setup_auth.py          # One-time OAuth 2.0 setup (browser-based)
~/.ticktick_mcp/       # Token storage (auto-refreshed)
skills/ticktick/       # Claude skill for natural task language

Design choices:

• Async everywhere -- httpx.AsyncClient for non-blocking API calls
• Pydantic input models -- Type-safe, validated inputs with clear error messages
• MCP annotations -- readOnlyHint, destructiveHint for safer tool usage
• Auto token refresh -- Tokens refresh transparently with a 60-second buffer

---

Troubleshooting

"Given client ID does not match" -- Double-check your Client ID on developer.ticktick.com.

Port 8080 already in use -- lsof -ti:8080 | xargs kill -9 then retry.

Tokens expired -- Re-run setup_auth.py to get fresh tokens.

Claude doesn't see tools -- Run claude mcp list to verify registration.

---

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Make your changes to server.py
# Test: python3 -c "from server import mcp; print(len(mcp._tool_manager._tools), 'tools')"

---

Links

• GitHub
• Glama
• Report an issue
• TickTick Developer Portal
• TickTick API Docs

---

License

MIT (c) Salen-Project