---
name: TickTick Integration
description: TickTick API integration for project/task management - OAuth credentials in SOPS vault, MCP server, API service
type: reference
---

## TickTick Integration (Built 2026-03-31)

**App Name:** ClaudeTools (registered at developer.ticktick.com)

### Credentials
- SOPS vault: `services/ticktick.sops.yaml`
- Fields: `credentials.client_id`, `credentials.client_secret`, `credentials.oauth_redirect_url`
- OAuth tokens: `mcp-servers/ticktick/.tokens.json` (gitignored, auto-refreshed)

### Components
- **MCP Server:** `mcp-servers/ticktick/ticktick_mcp.py` - 9 tools for Claude Code (registered in `.mcp.json`)
- **OAuth Auth:** `mcp-servers/ticktick/ticktick_auth.py` - One-time browser auth flow (localhost:9876 callback)
- **API Service:** `api/services/ticktick_service.py` - Async service, SOPS vault credentials, auto token refresh
- **API Router:** `api/routers/ticktick.py` - REST at `/api/ticktick/`, JWT-protected

### TickTick API
- Base URL: `https://api.ticktick.com/open/v1`
- Auth: OAuth 2.0 Bearer tokens, scopes: `tasks:read tasks:write`
- No webhooks (must poll), no search endpoint (filter client-side)
- Priority values: 0=none, 1=low, 3=medium, 5=high (non-sequential)
- Token endpoint requires `application/x-www-form-urlencoded` (not JSON)

### MCP Tools
`ticktick_list_projects`, `ticktick_get_project`, `ticktick_create_project`, `ticktick_update_project`, `ticktick_delete_project`, `ticktick_create_task`, `ticktick_update_task`, `ticktick_complete_task`, `ticktick_delete_task`

### Re-auth
If tokens expire completely, run: `python mcp-servers/ticktick/ticktick_auth.py` from bash (not PowerShell - needs vault access via bash).