TimeTree MCP

TimeTree MCP is an unofficial Model Context Protocol server that accesses TimeTree calendars over HTTPS. It uses the Python direct client by default and does not launch a browser; the browser transport is kept only as a compatibility fallback. Session cookies and CSRF tokens exist only in the MCP process memory.

Important: TimeTree's official Connect App/API has been discontinued. This project uses TimeTree Web's non-public endpoint, which may stop working when the service changes. Please assess the risks yourself and comply with TimeTree's terms and policies.

Features

• Read calendars, events, memos, comments, labels, and members.

• Create, update, and delete events and memos.

• Add, update, and delete event comments.

• Update calendar labels using merge mode.

• Monitor calendar changes in the background and send MCP notifications.

• All write operations require explicitly passing confirm: true.

• Credentials are not placed in MCP tool arguments; the authenticated session is kept only in memory.

Related MCP server: Apple Calendar MCP

Requirements

• Python 3.10 or later.

• A TimeTree account.

• macOS is required to use the Keychain helper; other platforms can use environment variables or a password file.

Installation

git clone <repository-url>
cd timetree-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --editable .

The runtime uses only the Python standard library. After installation, the timetree-mcp and timetree-credentials commands are available.

Using the NPM wrapper

The NPM wrapper requires Node.js 18+ and Python 3.10+; it launches the Python MCP server bundled with the package and forwards MCP's stdin/stdout:

npx --yes timetree-mcp

It can also be installed globally:

npm install --global timetree-mcp
timetree-mcp

Setting up credentials

Using the Keychain on macOS is recommended. When setting it up, the password is only entered hidden in the terminal; it does not enter shell history, MCP arguments, or source code:

./scripts/setup_timetree_keychain.sh
timetree-credentials status

MCP automatically reads the email/password in the Keychain. status only reports whether they exist and does not return values; clear both Keychain items:

timetree-credentials clear

If you are not using the Keychain, you can also use environment variables:

export TIMETREE_EMAIL='your-email@example.com'
export TIMETREE_PASSWORD='your-password'

An even better option is to use a password file with permissions of 600:

chmod 600 /absolute/path/to/timetree-password
export TIMETREE_EMAIL='your-email@example.com'
export TIMETREE_PASSWORD_FILE='/absolute/path/to/timetree-password'

Registering with Codex

Replace /absolute/path/to/timetree-mcp with your checkout location. If a timetree server with the same name already exists, remove it and then add it again:

codex mcp remove timetree
codex mcp add timetree \
  --env TIMETREE_EMAIL=your-email@example.com \
  --env TIMETREE_PASSWORD_FILE=/absolute/path/to/timetree-password \
  -- python3 /absolute/path/to/timetree-mcp/src/timetree_mcp/server.py

Do not put the actual password in shell history, MCP tool arguments, the README, or source code.

When registering with the NPM wrapper, change the server command to:

codex mcp add timetree \
  --env TIMETREE_EMAIL=your-email@example.com \
  --env TIMETREE_PASSWORD_FILE=/absolute/path/to/timetree-password \
  -- npx --yes timetree-mcp

MCP tools

Login and read

• timetree_login, timetree_logout, timetree_status

• timetree_keychain_status

• timetree_list_calendars, timetree_list_events, timetree_list_memos

• timetree_list_event_comments

• timetree_get_calendar_labels, timetree_get_calendar_members, timetree_get_calendar_virtual_members

Writes

• timetree_create_event, timetree_update_event, timetree_delete_event

• timetree_create_memo, timetree_update_memo, timetree_delete_memo

• timetree_add_event_comment, timetree_update_event_comment, timetree_delete_event_comment

• timetree_update_calendar_labels

Time can be passed as an ISO-8601 string or Unix milliseconds; all write tools must explicitly pass confirm: true. Member invitation/removal endpoints are not yet verified, so they are intentionally not included.

If some older calendars' TimeTree sync endpoint returns -425, event queries skip that calendar and report it in the skipped_calendars field, without causing the whole batch of other readable calendars to fail.

Background monitoring

• timetree_start_monitor: Starts background polling, with an interval of 30–3600 seconds.

• timetree_monitor_status: Views monitoring status, last poll, errors, and notification count.

• timetree_stop_monitor: Stops monitoring.

The first poll only establishes a baseline; afterward, when additions, modifications, or removals are detected, the server sends MCP notifications/message. The monitor is tied to the MCP process and also stops when the client exits.

Project structure

src/timetree_mcp/          Python package 與 MCP server
bin/                       NPM wrapper launcher
scripts/                   本機設定輔助腳本
tests/                     standard-library unittest 測試
test/                      NPM wrapper 測試
.github/workflows/ci.yml   Continuous integration

Testing

python3 -m unittest discover -s tests -v
npm test

The legacy ego-browser transport is kept at src/timetree_mcp/browser.py as a compatibility fallback, but the server does not load it by default.

License

This project is licensed under the MIT License.