TickTick MCP — remote connector for Claude

A single-user remote MCP server that lets Claude create and manage TickTick to-dos. Because it's a remote connector (Claude reaches it over HTTPS from Anthropic's cloud), one deployment works on all platforms: claude.ai web, the mobile apps, Claude Desktop, and Cowork.

It wraps the TickTick Open API and exposes nine tools:

Tool	What it does
list_projects	List your projects/lists (call first to get a projectId)
list_sections	List a kanban project's sections/columns (to get a columnId)
list_tasks	List open tasks in a project (with each task's section)
get_task	Full detail of one task
create_task	Create a to-do (Inbox, a project, or a kanban section)
update_task	Edit fields on a task (incl. moving it between sections)
complete_task	Mark a task done
delete_task	Permanently delete a task
create_project	Create a new list/project

Dates are handled for Africa/Harare (UTC+2) — pass YYYY-MM-DD (all-day) or YYYY-MM-DDTHH:MM (timed) and they land on the day you mean.

---

Setup (about 20 minutes, one time)

1. Register a TickTick app

Go to https://developer.ticktick.com, create an app, and set its redirect URI to:

http://localhost:8080/callback

Note the Client ID and Client Secret.

2. Get an access token

npm install
npm run auth

Paste your Client ID/Secret when prompted, authorize in the browser, and the script prints your TICKTICK_ACCESS_TOKEN. TickTick issues a long-lived token (~180 days) and no refresh token, so re-run npm run auth and update the env var when it expires.

3. Generate a URL secret

node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"

This becomes the secret path segment in your connector URL. Treat it like a password.

4. Test locally first (optional but recommended)

You don't need the Vercel CLI to test. Create .env.local (copy .env.example) with all four vars, then:

npm start

This serves the exact production handler on http://localhost:8080. Connect Claude Code:

claude mcp add --transport http ticktick http://localhost:8080/api/<MCP_SHARED_SECRET>/mcp

Then ask Claude Code to list your TickTick projects to confirm it works end to end.

5. Deploy to Vercel

Create a new Vercel project from this folder, then add these environment variables (Project → Settings → Environment Variables):

• TICKTICK_CLIENT_ID
• TICKTICK_CLIENT_SECRET
• TICKTICK_ACCESS_TOKEN
• MCP_SHARED_SECRET (the secret from step 3)

npm run deploy

Your endpoint is:

https://<your-app>.vercel.app/api/<MCP_SHARED_SECRET>/mcp

6. Add it to Claude

Settings → Connectors → Add custom connector → paste the full URL above → Add. Leave the OAuth fields blank (this server is authless; the secret in the URL is the guard). Once added on one platform it's available on all of them.

---

How it stays secure for a single user

There's no OAuth handshake between Claude and this server. Instead the secret lives in the URL path, and the server returns 404 to any request whose path secret doesn't match MCP_SHARED_SECRET. Your TickTick tokens never leave the server — Claude only ever calls the eight tools.

If you later want to share this with teammates (each hitting their own TickTick account), that's the point where you'd swap the path-secret model for a real OAuth flow. The tool logic in lib/ticktick.js wouldn't need to change.

Notes

• The server is stateless per request, which suits serverless — no session state to lose between cold starts.
• The TickTick access token is long-lived (~180 days) and used directly — TickTick's Open API doesn't issue refresh tokens, so there's no auto-refresh. Re-run npm run auth and update the env var when it expires.
• delete_task is irreversible; the tool description nudges Claude toward complete_task unless you clearly want deletion.