@reneza/ticktick-cli

Disclaimer: This is an unofficial, community-maintained project and is not affiliated with, endorsed by, or connected to TickTick or Appest. "TickTick" is a trademark of Appest. This tool uses the official TickTick Open API.

TickTick task management for Claude Code, Claude Desktop, and the terminal. 17 MCP tools for creating, searching, completing, and organizing tasks — plus optional semantic vector search via Qdrant + Ollama.

Fork of kvanland/ticktick-cli with semantic search, completed tasks filtering, and Claude Code plugin marketplace support.

Install

npm install -g @reneza/ticktick-cli
ticktick setup

The setup wizard walks you through creating an app at developer.ticktick.com and completing OAuth.

MCP Server — Claude Code

claude mcp add ticktick ticktick-mcp

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ticktick": {
      "command": "ticktick-mcp"
    }
  }
}

Claude Code Plugin Marketplace

/plugin marketplace add ticktick-cli https://github.com/renezander030/ticktick-cli
/plugin install ticktick@ticktick-cli

Registers the MCP server automatically — no manual config needed.

MCP Server — Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "ticktick-mcp"
    }
  }
}

MCP Tools

| Tool | Description | |------|-------------| | ticktick_auth_status | Check authentication status | | ticktick_projects_list | List all projects | | ticktick_projects_get | Get project with tasks | | ticktick_tasks_list | List tasks in project | | ticktick_tasks_get | Get task details | | ticktick_tasks_create | Create a new task | | ticktick_tasks_update | Update an existing task | | ticktick_tasks_complete | Mark task as complete | | ticktick_tasks_delete | Delete a task | | ticktick_tasks_search | Search by keyword, tags, or priority | | ticktick_tasks_semantic_search | Semantic search via vector similarity | | ticktick_tasks_similar | Find semantically similar tasks | | ticktick_tasks_due | Get tasks due within N days | | ticktick_tasks_priority | Get high priority tasks | | ticktick_tasks_completed | List completed tasks within a date range | | ticktick_vector_sync | Sync tasks into vector index | | ticktick_vector_status | Check vector index health |

Example prompts:

• "What tasks do I have due this week?"
• "Create a task to buy groceries tomorrow with high priority"
• "Find tasks related to deployment"
• "Show me what I completed last week"

CLI Usage

# Tasks
ticktick tasks create "Buy groceries" --due 2026-01-30 --priority high --tags "shopping"
ticktick tasks due 3                    # Due in 3 days
ticktick tasks search "meeting"         # Keyword search
ticktick tasks search --tags "work"
ticktick tasks completed                # Last 7 days
ticktick tasks completed --start 2026-01-01 --end 2026-01-31

# Projects
ticktick projects list
ticktick projects create "Name" --color "#ff6b6b"

# Auth
ticktick auth status
ticktick auth login

All IDs are displayed as 8-character short IDs. Use --format json for machine-readable output.

Semantic Vector Search (Optional)

Keyword search fires N+1 API calls per query and only does substring matching. Vector search queries a local Qdrant index in <100ms and finds semantically related results ("deployment" matches "push release to prod").

Entirely optional — if Qdrant/Ollama aren't running, semantic search falls back to keyword search automatically.

Setup

# Start Qdrant and Ollama (Docker)
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
docker run -d --name ollama -p 11434:11434 ollama/ollama
docker exec ollama ollama pull nomic-embed-text

# Build the index
ticktick tasks vector-sync

# Search
ticktick tasks semantic "anything about deployments"
ticktick tasks similar TASK_ID

Sync is incremental — only re-embeds tasks whose content changed. Set up a cron job for automated updates:

0 */4 * * * ticktick tasks vector-sync --format json >> /var/log/ticktick-vector-sync.log 2>&1

Configuration

| File | Purpose | |------|---------| | ~/.config/ticktick/config.json | Client credentials | | ~/.config/ticktick/tokens.json | OAuth tokens (auto-managed) |

Environment variables: TICKTICK_CLIENT_ID, TICKTICK_CLIENT_SECRET, QDRANT_URL, OLLAMA_URL, EMBEDDING_MODEL

License

MIT — see LICENSE. Originally created by kvanland.