Skip to main content
Glama

timetree-mcp

個人使用的非官方 TimeTree MCP,專門讀取、新增及更新自己帳號中的非公開「共用行事曆」。日曆仍由 TimeTree 既有成員共用,MCP 不會把它轉成公開日曆。

TimeTree 已於 2023-12-22 停止官方 Connect API。本專案使用非官方 web API,可能隨服務變動失效,沒有官方支援。Endpoint 與事件格式參考 ehs208/TimeTree-MCP(MIT),並未匯入其程式。請自行確認服務使用條款。

安裝與設定

需要 Node.js 18+。在本專案目錄執行:

npm install
npm run build
if (!(Test-Path .env)) { Copy-Item .env.example .env }

使用 email 登入時,在本機 .env 填入 TIMETREE_EMAIL 與 TIMETREE_PASSWORD。Google/Apple 登入請使用下方的本機 session 匯入。不要把密碼或 session 貼到對話、命令列或同步筆記;.env 已被 git 忽略。

Google 登入的本機 session 匯入

本程式不代替 Google 登入,也不讀取 Chrome cookie 資料庫。先在 Chrome 登入 TimeTree,開啟 DevTools → Application → Cookies → https://timetreeapp.com,找到 _session_id,只複製 Value 欄位,然後在本專案目錄的 PowerShell 執行:

& .\scripts\Import-TimeTreeSession.ps1

腳本只把剪貼簿中的值寫入 gitignored .env 的 TIMETREE_SESSION_COOKIE,保留其他設定,不印出值,完成後清空剪貼簿;含換行、空白或 Cookie header 的輸入會拒絕。Session 等同帳號憑證,不要貼到聊天。若 PowerShell 不允許執行腳本,可以直接在本機編輯 .env,同樣不要將值輸出或分享。

使用 session 時不需要 TimeTree 密碼;session 優先於帳密。過期時本機重新登入與匯入,不會自動改用帳密重試。CSRF 仍從 TimeTree 頁面讀取,缺少 CSRF 不會送出寫入。Session 交接方式參考 第三方實作的認證文件,不是官方支援的 API。

連接 Codex App

在專案目錄執行以下命令,讓 Codex 記住實際的 server 絕對路徑;命令不包含帳號密碼:

codex mcp add timetree-private -- (Get-Command node).Source (Join-Path (Get-Location) 'dist/index.js')

也可以在本機 ~/.codex/config.toml 加入以下設定,將路徑換成實際位置:

[mcp_servers.timetree-private]
command = "node"
args = ['C:\path\to\TimeTree-MCP\dist\index.js']

Codex App 與 CLI 共用這份 MCP 設定,見 OpenAI 官方 MCP 文件。本機 codex mcp add --help 已確認命令格式。設定完成後重新啟動 Codex;可用 codex mcp list 檢查註冊。這個 server 使用自己的 TimeTree 帳號登入流程,不使用 codex mcp login 的 OAuth。

沒有 credentials 時 server 仍可啟動、列出四個工具,但所有日曆呼叫會回傳驗證失敗;填好本機 .env 或匯入 session 後重新啟動。沒有設定日曆 ID 時,可先完成以下 discovery:

  1. 呼叫 list_calendars,從目前帳號可存取的日曆找出「共用行事曆」的 ID。

  2. 把 ID 填入本機 .env 的 TIMETREE_CALENDAR_ID,重新啟動 MCP。

  3. 先呼叫 list_events 確認日曆與日期範圍,再新增或更新正式事件。

名稱只用於人工辨識;若有多個同名日曆,必須先確認正確 ID,程式不會任選。沒有設定有效 ID 時,只有 list_calendars 可用。所有事件操作只使用鎖定的 ID,不接受工具參數覆寫日曆。設定錯誤但有效的 ID 仍會操作該日曆,請先確認讀回內容。

伺服器從專案根目錄載入 .env;既有 process 環境變數優先。匯入的 session 會保存在本機 .env;程式執行時的 session/CSRF 更新只存於記憶體。登入失效需本機刷新 session 並重新啟動 MCP;寫入遇到 timeout 或錯誤時不自動重送,請先讀回確認是否已建立,以免重複事件。

Related MCP server: TimeTree MCP Server

工具

只提供 list_calendars、list_events、create_event、update_event。不再提供公開日曆、圖片上傳或海報檔案搬移工具。

  • list_calendars {}:列出帳號可存取的有效日曆 ID 與名稱,用於第一次設定。

  • list_events {"from":"2026-11-01","to":"2026-12-01"}:列出鎖定日曆與 [from,to) 重疊的事件,回傳 uuid 供更新使用。會同步所有分頁後依日期篩選;遇到不完整分頁會回報錯誤。

  • create_event {"title":"晚餐","start":"2026-11-05T18:00","end":"2026-11-05T20:00"}:新增一般事件;未給 end 預設一小時。

  • create_event {"title":"休假","start":"2026-11-05","end":"2026-11-06","all_day":true}:全日日期包含 end,以上為 11/5–11/6 兩天;未給 end 為單日。

  • update_event {"event_uuid":"從 list_events 取得的 uuid","title":"新標題"}:先讀取原事件,再保留未指定欄位送出更新,包括附件、checklist、提醒、重複設定及未知欄位。link_url 只修改 attachment.url,空字串可清除連結。

日期使用當地 YYYY-MM-DD 或 YYYY-MM-DDTHH:mm[:ss],不接受尾端 Z 或 UTC offset。timezone 預設 Asia/Taipei;DST 不存在或有兩種解讀的時間會拒絕。全日事件只接受日期。更新時若變更 timezone 或 all_day,必須同時提供 start/end;只改 start 不會自動移動原 end。時間或範圍不合法會拒絕。

新增與更新還可指定 location、description、link_url(HTTP/HTTPS)與 label_id(1–10)。新增預設一般事件,不預設指定出席成員;日曆其他成員仍可能看見變更或收到通知。同一 MCP 程序會循序處理同一事件的更新,避免自己的兩個更新互相覆蓋;不同事件可以並行。讀取後到寫入之間若其他成員或其他程序同時改動事件,仍有覆蓋風險;非官方 API 沒有已驗證的版本鎖定機制。

驗證

npm run typecheck
npm run build
node --test tests/private-calendar.test.mjs
& .\tests\session-import.test.ps1

測試使用 mock fetch 驗證私人 endpoint、固定 ID、更新欄位保留、日期與分頁,以及本機 MCP 握手。這些是離線驗證,不能證明真實帳號登入、權限或 TimeTree 實際寫入成功。需在本機設定帳號和日曆 ID 後,再驗證實際讀寫。獨立安全審查見 reports/security.md;依賴 audit 因沒有 lockfile 而回報 ENOLOCK,尚未完成。

Available Tools

6 tools
create_eventA

Create an event in a TimeTree public calendar that the authenticated account manages. Use this after reading an event poster: pass alias_code (from list_calendars), title, ISO start date, optional location, and a short description (1-2 sentences). Timezone defaults to Asia/Taipei. Returns the created event with id and public URL.

Inputs: start (required), title (required), alias_code (required), end, +7 more.

list_calendarsA

List configured TimeTree public calendars. Without args, returns the calendars set in TIMETREE_CALENDAR_ALIASES env var. Pass alias_codes to override (each code is the short ID in the URL https://timetr.ee/p/). Returns calendar id, alias_code, name, category, subscription count, and label palette.

Inputs: alias_codes.

list_eventsA

List events in a TimeTree public calendar within a date range. Pass alias_code (from list_calendars) and ISO date strings for from/to. Timezone defaults to Asia/Taipei.

Inputs: to (required), from (required), alias_code (required), timezone.

mark_poster_processedA

Move one poster image out of 00_待處理 after processing and append the CSV log. Normally create_event/update_event do this automatically when image_path is inside 00_待處理. Use this for manual corrections or posters that need review.

Inputs: status (required), image_path (required), end, root, +5 more.

poster_workspace_statusA

Prepare and inspect the local poster workflow folder. Creates the standard folders if missing, moves loose image files from the root into 00_待處理 by default, and returns only pending poster image paths that should be read next.

Inputs: root, move_loose_images_to_pending.

update_eventA

Update an existing event in a TimeTree public calendar (full replace — PUT). Use this to add/replace/remove a cover image on an existing event, or change title/time/etc. Pass event_id (from list_events) plus all the fields you want the event to have. For cover: pass image_path to upload+set a new one, or remove_image=true to clear it; if neither is passed, cover is CLEARED (PUT is full-replace). To preserve the current cover while editing other fields, you must re-upload via image_path.

Inputs: start (required), title (required), event_id (required), alias_code (required), +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: calendar listing, event listing, event creation, event updating, poster workspace inspection, and poster processed marking. No two tools overlap in function, and the descriptions reinforce the boundaries.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (list_calendars, list_events, create_event, update_event, mark_poster_processed). The exception is poster_workspace_status, which uses a noun_noun structure, but it is still understandable and does not create confusion.

    Tool Count5/5

    Six tools is well-scoped for the server's dual purpose of TimeTree calendar management and local poster workflow. Each tool earns its place without redundancy or unnecessary bloat.

    Completeness4/5

    The server covers the core lifecycle of events (list, create, update) and the poster workflow (status, mark processed, integrated image upload). Minor gaps include no delete_event or get_single_event, but these can be worked around with list_events and update_event, so the coverage is adequate for typical use.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers