# TickTick MCP — remote connector for Claude

A single-user remote [MCP](https://modelcontextprotocol.io) 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](https://developer.ticktick.com) 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
```bash
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
```bash
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:
```bash
npm start
```
This serves the exact production handler on `http://localhost:8080`. Connect Claude Code:
```bash
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)

```bash
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.