⚠️ DISCLAIMER: This is an UNOFFICIAL TimeTree MCP server for PERSONAL USE ONLY. Not affiliated with TimeTree, Inc. May break at any time. See DISCLAIMER.md for full details.
Use Claude, Codex, Cursor, Windsurf, and other MCP clients to read and manage your TimeTree calendars, events, memos, comments, labels, and members — locally, with credentials kept in your MCP client configuration.
Credits: This project was inspired by and uses API insights from TimeTree-Exporter by @eoleedi.
- 📅 List Calendars - Get all your TimeTree calendars
- 📆 Get Events - Retrieve events from any calendar with automatic pagination
- ➕ Create Events - Add new events to your calendars
- ✏️ Update Events - Modify existing events
- 🗑️ Delete Events - Remove events from your calendars
- 🗒️ Manage Memos - List, create, update, and delete TimeTree memos
- 💬 Manage Comments - Add, list, update, and delete event comments
- 🏷️ Calendar Metadata - Read/update labels and inspect members/virtual members
- 🔐 Secure Authentication - Email/password authentication (stored only in MCP config)
- ⚡ Rate Limiting - Token bucket algorithm to prevent API overload
- 🔄 Auto Pagination - Automatically fetches all events across multiple pages
- 🛡️ Error Handling - Comprehensive error handling with user-friendly messages
- 📝 Structured Logging - Detailed logs with sensitive data masking
- Node.js >= 18.0.0
- Git (for installation)
- A TimeTree account
- An MCP-compatible client (Claude Desktop, Claude Code, Codex, Antigravity, Cline, etc.)
Copy this prompt into Codex, Claude Code, or another coding agent:
Clone
https://github.com/ehs208/TimeTree-MCP, enter the cloned directory, runnpm ci && npm run build, then configure my MCP client with a server namedtimetreethat runsnode /absolute/path/to/TimeTree-MCP/dist/index.js(use the real cloned path). StoreTIMETREE_EMAILandTIMETREE_PASSWORDonly in the MCP client environment configuration, and never hardcode or print secrets.
If this saved you time, please star the repo: https://github.com/ehs208/TimeTree-MCP
One-line installation - Automatically clones, builds, attempts optional npm link, and prints client configuration examples:
curl -fsSL https://raw.githubusercontent.com/ehs208/TimeTree-MCP/main/TimeTree-MCP-install.sh | bashThis project is installed from a GitHub clone, not the npm registry. The script builds the local clone, optionally runs npm link, then prints configuration instructions with absolute node/dist/index.js paths for all supported MCP clients. Just copy the config for your client and add your TimeTree credentials.
Click to expand manual installation steps
- Clone and build:
git clone https://github.com/ehs208/TimeTree-MCP.git
cd TimeTree-MCP
npm ci
npm run build- Configure your MCP client:
See the Configuration section below to set up your MCP client.
Quick Example (Claude Desktop - macOS):
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"timetree": {
"command": "node",
"args": ["/absolute/path/to/TimeTree-MCP/dist/index.js"],
"env": {
"TIMETREE_EMAIL": "your-email@example.com",
"TIMETREE_PASSWORD": "your-password"
}
}
}
}Replace the path with your cloned repository path. If a GUI client cannot find node, use the absolute path from command -v node as command. Then restart Claude Desktop (Cmd+Q and reopen).
📖 For all MCP clients (Claude Desktop Windows, Claude Code CLI, Codex, Antigravity, VS Code editors, etc.): → See docs/MCP_CLIENTS.md for detailed configuration instructions
To update to the latest version:
cd /path/to/TimeTree-MCP # or your installation path
git pull origin main
npm ci
npm run buildThen restart your MCP client.
📖 For detailed update instructions and troubleshooting: → See docs/UPDATING.md
📖 See COMMANDS.md for detailed usage examples and workflows
- list_calendars - List all calendars with participating users
- get_events - Get events from a calendar with auto-pagination
- get_updated_events - Get events updated after a specific timestamp (efficient incremental sync)
- create_event - Create a new event in a calendar (supports alerts, recurrences, attendees, checklist)
- update_event - Update an existing event
- delete_event - Delete an event from a calendar
- list_memos / create_memo / update_memo / delete_memo - Manage TimeTree memos
- add_event_comment / list_event_comments / update_event_comment / delete_event_comment - Manage event comments
- get_calendar_labels / update_calendar_labels - Read or merge-update calendar labels
- get_calendar_members / get_calendar_virtual_members - Read calendar member metadata
📖 See COMMANDS.md for parameters and usage details.
# Build the project
npm run build
# Watch mode (auto-rebuild on changes)
npm run dev- Unofficial API: May break if TimeTree changes their internal API
- Rate Limited: 10 requests/second (with automatic retry for 429 errors)
- No Official Support: TimeTree does not officially support this tool
- CSRF Token Required: Write operations require CSRF token (automatically extracted from TimeTree web page)
- Credentials are stored only in your local MCP configuration
- Session cookies are stored in memory only (never persisted to disk)
- Passwords and session IDs are automatically masked in logs
- All communication uses HTTPS
Make sure TIMETREE_EMAIL and TIMETREE_PASSWORD are set in your MCP configuration.
- Verify your email and password are correct
- Check if you can log in to TimeTree web app
- TimeTree might have changed their authentication API
- Verify you have calendars/events in your TimeTree account
- Check the logs for detailed error messages
- The API might have changed
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License - see LICENSE file for details.
If this project helps you, please consider giving it a GitHub Star. It helps others discover the project.
See DISCLAIMER.md for important legal and usage information.
NOT AFFILIATED WITH TIMETREE, INC.
This is an independent, community-maintained project.