TimeTree-MCP
The server schema exposes TimeTree public-calendar management and a local poster workflow, which differs from the README’s private-calendar-only description.
List configured or requested public calendars by alias code, including calendar metadata and label palette.
List events in a public calendar over a date range with timezone handling.
Create events with title, time/all-day, location, description, link, label, timezone, and optional cover image.
Update existing events via full replacement, including changing fields and adding/removing cover images.
Prepare/inspect a local poster workspace and list pending poster images.
Mark poster images as processed by moving them to status folders and logging event metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TimeTree-MCP Show me my events for this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
呼叫
list_calendars,從目前帳號可存取的日曆找出「共用行事曆」的 ID。把 ID 填入本機
.env的TIMETREE_CALENDAR_ID,重新啟動 MCP。先呼叫
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 toolscreate_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
MCP server providing attendance data queries via the CloudTime API.
The official Planning Center MCP server for interacting with your ministry's data.
A MCP server that works with Google Calendar to manage event listing, reading, and updates.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that integrates with the Tweek API to manage calendars, tasks, and custom colors. It enables users to perform full task CRUD operations, list accessible calendars, and fetch color preferences through secure authentication.1MIT
- AlicenseAqualityBmaintenanceUnofficial MCP server for accessing and managing TimeTree calendar data, including events, memos, and comments, with secure email/password authentication.2932MIT
- AlicenseAqualityBmaintenanceMCP server for Apple Calendar and CalDAV providers. Enables listing, creating, updating, deleting events, and checking free/busy status with per-calendar write protection.6MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for the Teamup Calendar API, enabling event management, calendar listing, and available slot search.-