TimeTree-MCP

[!NOTE] Unofficial and for personal use. Not affiliated with TimeTree, Inc. It uses the TimeTree web app's undocumented endpoints, which can change at any time. See DISCLAIMER.md.

Ask your AI assistant things like:

• "Summarize our family calendar this week. Any conflicts?"
• "When was the last dentist appointment?"
• "Add a dinner on Saturday at 7 pm to the Family calendar."
• "Turn this trip plan into events and a packing memo."
• "Who changed the calendar today, and what did they change?"

What it does

• Reads your calendars. Events with date, keyword, and label filters. Recurring events are expanded into their actual dates.
• Reads comment images. Pass images attached to event comments to your AI client, including images posted by free accounts.
• Changes them when you ask. Create, update, copy, and delete events, memos, and comments, and rename or recolor labels. Change or delete a single occurrence of a recurring event, or it and the ones after it.
• Manages virtual members. Add, rename, or remove members without a TimeTree account, such as children or pets.
• Keeps you up to date. See what changed since a given time, and who made recent changes.
• Knows the context. Calendar members and public holidays by country.
• Runs on your computer. Your email and password are sent only to TimeTree. The session stays in memory.

Install

Claude Desktop (macOS, Windows): one-click extension

1. Download timetree-mcp-<version>.mcpb from the latest release.
2. Open the file. Claude Desktop shows an install dialog.
3. Enter your TimeTree email and password, then enable the extension.

No Git, Node.js install, or config file editing is needed. The extension runs on the Node.js that comes with Claude Desktop on macOS and Windows.

Claude Code, Codex, Cursor, and other clients

Requires Node.js 22 or later and Git.

Ask your coding agent. Paste this into Claude Code, Codex, or a similar agent:

Clone https://github.com/ehs208/TimeTree-MCP, enter the cloned directory, run npm ci && npm run build, then configure my MCP client with a server named timetree that runs node /absolute/path/to/TimeTree-MCP/dist/index.js (use the real cloned path). Store TIMETREE_EMAIL and TIMETREE_PASSWORD only in the MCP client environment configuration, and never hardcode or print secrets.

Or run the installer. It clones, builds, and prints a config example for each client:

curl -fsSL https://raw.githubusercontent.com/ehs208/TimeTree-MCP/main/TimeTree-MCP-install.sh | bash

git clone https://github.com/ehs208/TimeTree-MCP.git
cd TimeTree-MCP
npm ci
npm run build

Then add the server to your MCP client. Example for Claude Desktop on macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "timetree": {
      "command": "node",
      "args": ["/absolute/path/to/TimeTree-MCP/dist/index.js"],
      "env": {
        "TIMETREE_EMAIL": "[email protected]",
        "TIMETREE_PASSWORD": "your-password"
      }
    }
  }
}

If a GUI client cannot find node, use the absolute path from command -v node as command.

Setup for each client (Claude Code, Codex, Cursor, Windsurf, VS Code, Antigravity, and more): docs/MCP_CLIENTS.md

This project is not published to npm. Install it from a GitHub release or a clone of this repository.

Updating

When a newer version is out, the server adds a one-time notice to a tool response, so your assistant can tell you. Set TIMETREE_UPDATE_CHECK=false in the MCP env to turn this off.

• Claude Desktop extension: download the new .mcpb from the latest release and open it.
• Git clone: run git pull origin main && npm ci && npm run build in the folder, then restart your MCP client.

Details: docs/UPDATING.md. Changes: CHANGELOG.md.

Tools

Area	Tools
Calendars	list_calendars, create_calendar, get_current_user
Events	get_events, get_updated_events, create_event, update_event, delete_event, copy_event
Recurring events	update_event_occurrence, delete_event_occurrence
Memos	list_memos, create_memo, update_memo, delete_memo
Comments	list_event_comments, get_event_comment_image, add_event_comment, update_event_comment, delete_event_comment
Labels and members	get_calendar_labels, update_calendar_labels, get_calendar_members, get_calendar_virtual_members, create_virtual_member, update_virtual_member, delete_virtual_member
Other	get_holidays, get_recent_activity

Parameters and examples: COMMANDS.md

create_calendar requires a name (1–20 characters) and an explicit purpose. It does not invite members. Timeouts and server errors are not retried. If the creation response cannot be validated, check existing calendars before trying again.

list_event_comments includes image metadata. Use get_event_comment_image to retrieve one image as standard MCP image content over stdio; the client must support image tool results. JPEG, PNG, GIF, and WebP up to 5 MiB are supported. Images stay in memory and are not saved to disk. Premium files attached directly to an event and image uploads are not supported.

Privacy and security

• Your email and password are stored only in your MCP client configuration, or in Claude Desktop's extension settings. They are sent only to TimeTree.
• Session cookies and CSRF tokens stay in memory and are never written to disk.
• Logs mask passwords, cookies, and tokens.
• On startup, the server makes one request to GitHub to check for a newer version. No credentials or calendar data are sent.

Troubleshooting

"Missing required environment variables": set TIMETREE_EMAIL and TIMETREE_PASSWORD in your MCP configuration. For the Claude Desktop extension, open its settings and enter them again.

Sign-in fails: check that you can sign in on the TimeTree web app with the same email and password. The server signs in with email and password only.

No calendars or events: make sure the account has calendars, and check the client's MCP logs. TimeTree may have changed its web API; please open an issue.

How it works

The server signs in to the TimeTree web app with your email and password, then calls the same endpoints the web app uses. It signs in again when the session expires, limits requests to 10 per second with retries on HTTP 429, and reads every page of large calendars.

Write requests need a CSRF token, which the server reads from the TimeTree web page after signing in.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Thanks to everyone who has contributed.

Credits

API insights from TimeTree-Exporter by @eoleedi.

License

MIT. See LICENSE. Not affiliated with TimeTree, Inc. See DISCLAIMER.md.