timetree-mcp

A personal-use MCP server that lets Claude write events into your shared TimeTree calendar. Typical flow: paste an event poster → Claude extracts date / location / title and writes a short description → calls create_event → event shows up in the TimeTree app.

⚠️ Disclaimer (read before using)

• TimeTree's official Connect API was shut down on 2023-12-22. This MCP talks to TimeTree's internal web API (the same one the web app uses), reverse-engineered.

• This is unofficial and not affiliated with TimeTree, Inc. It may break at any time if TimeTree changes the internal API. Using it may violate TimeTree's Terms of Service.

• Use a dedicated TimeTree account, not your main one. Invite that account to the shared calendar(s) you want to manage. If TimeTree flags the account, only the dedicated one is at risk.

• Personal use only. Don't publish this, don't run it at scale, don't make commercial use of it.

Endpoint mapping informed by ehs208/TimeTree-MCP (MIT) and eoleedi/TimeTree-Exporter.

Related MCP server: TimeTree MCP Server

Install

Requires Node.js 18+.

cd C:\Users\user\Desktop\timetree-mcp
npm install
npm run build

Configure

Copy .env.example to .env and fill in your dedicated account:

TIMETREE_EMAIL=dedicated-bot@example.com
TIMETREE_PASSWORD=...
LOG_LEVEL=INFO

The server reads .env from the project root at startup, so you do NOT need to pass credentials on the claude mcp add command line (that would put them in PowerShell history). Just register the binary:

claude mcp add timetree node "C:\Users\user\Desktop\timetree-mcp\dist\index.js"

Or, if you prefer editing config directly (e.g. ~/.claude/settings.json):

{
  "mcpServers": {
    "timetree": {
      "command": "node",
      "args": ["C:\\Users\\user\\Desktop\\timetree-mcp\\dist\\index.js"]
    }
  }
}

Restart Claude Code. /mcp should show timetree with the TimeTree tools, including list_calendars, list_events, create_event, update_event, poster_workspace_status, and mark_poster_processed.

Process-level env vars still override the .env file, so CI / one-off invocations can set TIMETREE_PASSWORD=xxx node dist/index.js to bypass it.

Usage

Poster folder workflow

Use a single poster workspace folder, defaulting to:

C:\Users\daan\Desktop\timetree海報更新

The MCP manages this structure:

timetree海報更新
├─ 00_待處理
├─ 10_已新增
├─ 20_已更新既有事件
├─ 90_需人工確認
└─ _log

Rules:

1. Put new poster images in 00_待處理.

2. Start by calling poster_workspace_status; it creates missing folders and lists only pending images.

3. When create_event succeeds with an image_path from 00_待處理, the poster is moved to 10_已新增.

4. When update_event succeeds with an image_path from 00_待處理, the poster is moved to 20_已更新既有事件.

5. Use mark_poster_processed with status: "needs_review" for unclear posters; they move to 90_需人工確認.

6. Every move appends a CSV record under _log.

If someone drops images directly into the workspace root, poster_workspace_status moves them into 00_待處理 by default so future runs still process only new items.

The intended workflow:

1. Drop an event poster (image) into a Claude Code conversation.

2. Ask Claude something like: "請把這張海報的活動加到我的家庭共用行事曆。"

3. Claude reads the poster, calls list_calendars to find the right calendar_id, writes a short description, and calls create_event with an ISO date.

4. Open TimeTree on your phone — the event is there.

Tools

list_calendars

No arguments. Returns {calendars: [{calendar_id, name, members}], total}. Use this first to know which calendar_id to write into.

create_event

Required: calendar_id (number), title (string), start (ISO 8601 string).

Optional:

• end — ISO 8601. Defaults to start + 1h for timed events, start (same day) for all-day.

• all_day — boolean (default false).

• timezone — IANA timezone (default Asia/Taipei).

• location — string.

• description — short note, shows up as the event note in TimeTree.

• label_id — 1-10. 1=Emerald 2=Cyan 3=Blue 4=Brown 5=Black 6=Red 7=Rose 8=Pink 9=Orange 10=Violet.

Returns the created event with its uuid (useful if you later add update_event / delete_event).

poster_workspace_status

Creates/checks the poster workspace folders, moves loose root-level images into 00_待處理 by default, and returns pending image paths.

mark_poster_processed

Moves a poster out of 00_待處理 and writes the CSV log. This is automatic for successful create_event and update_event calls when image_path points into 00_待處理, so this tool is mainly for manual corrections and needs_review.

Troubleshooting

• Invalid email or password — TimeTree returned 401. Check the dedicated account credentials. If the account uses social login (Google / Apple), it won't have an email/password and this MCP can't authenticate it. Use a TimeTree account created with email/password signup.

• CSRF token missing or invalid — usually means the session expired between calls. The client auto-reauths once on 403; if you see this twice in a row, TimeTree may have changed the CSRF token location.

• Empty list_calendars result — make sure the dedicated account is actually a member of at least one shared calendar.

• Build fails on Windows with esbuild ENOENT — known npm 10.8.x bug. Try npm install --no-package-lock or upgrade npm to 10.9+.

Project structure

src/
  index.ts      # MCP server entry (stdio transport)
  timetree.ts   # auth + HTTP + API client + logger
  tools.ts      # MCP tools: list_calendars, create_event
  types.ts      # Zod schemas and TS types

Four files, ~700 LOC. MVP scope. Extend by adding more handlers to buildTools in tools.ts.