Ticktick MCP

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?

---

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

---

MCP Tools Reference

Projects (5 tools)

Tasks -- Basic CRUD (7 tools)

Tasks -- Smart Queries (7 tools)

Tasks -- Batch & Productivity (5 tools)

Tasks -- Advanced Filters (2 tools)

User (1 tool)

---

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