How do I install the Salen-Project/ticktick-mcp MCP server?

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "ticktick-mcp": { "command": "npx", "args": ["-y", "Salen-Project/ticktick-mcp"] } }

What does Salen-Project/ticktick-mcp do?

[](https://glama.ai/mcp/servers/Salen-Project/ticktick-mcp) 🐍 ☁️ - TickTick MCP server using the official OAuth 2.0 API. Supports creating, listing, updating, completing, and deleting tasks. Includes a natural language skill for automatic task detection in Claude Cowork.

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

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')"

License

MIT (c) Salen-Project

Salen-Project/ticktick-mcp

Quick Install

Documentation Overview