TickTick MCP Server -- The Complete TickTick Integration for Claude

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