TickTick MCP Server -- The Complete TickTick Integration for Claude

![License: MIT](LICENSE) ![Version](https://github.com/Salen-Project/ticktick-mcp/releases) ![Python](https://python.org) ![Tools](#mcp-tools-reference) ![Glama](https://glama.ai/mcp/servers/Salen-Project/ticktick-mcp)

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

Go to developer.ticktick.com
Click New App and fill in any name
Set OAuth Redirect URL to: http://localhost:8080/callback
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

---

License

MIT (c) Salen-Project

ticktick-mcp