TimeTree MCP

TimeTree MCP は、非公式の Model Context Protocol server です。HTTPS 経由で TimeTree カレンダーにアクセスします。デフォルトでは Python direct client を使用し、ブラウザを起動しません。browser transport は互換性のための予備としてのみ残っています。session cookie と CSRF token は MCP process のメモリ内にのみ存在します。

重要： TimeTree 公式の Connect App／API は終了しました。本プロジェクトは TimeTree Web の非公開 endpoint を使用しているため、サービスが変更された場合に動作しなくなる可能性があります。自己責任でリスクを評価し、TimeTree の規約とポリシーを守ってください。

機能

• calendars、events、memos、comments、labels と members を読み取ります。

• events と memos の作成、更新、削除を行います。

• event comments の追加、更新、削除を行います。

• calendar labels を merge 方式で更新します。

• calendar の変更をバックグラウンドで監視し、MCP notifications を送信します。

• すべての書き込み操作では、confirm: true を明示的に渡す必要があります。

• credentials を MCP tool arguments に入れず、authenticated session はメモリ内にのみ保持します。

Related MCP server: TimeTree MCP Server

要件

• Python 3.10 以降。

• TimeTree アカウント。

• Keychain helper は macOS でのみ使用できます。他のプラットフォームでは環境変数または password file を使用できます。

インストール

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

Runtime が使用するのは Python standard library のみです。インストール後は timetree-mcp と timetree-credentials コマンドが提供されます。

NPM wrapper の使用

NPM wrapper には Node.js 18+ と Python 3.10+ が必要です。package 内の Python MCP server を起動し、 MCP の stdin/stdout を転送します：

npx --yes timetree-mcp

グローバルにインストールすることもできます：

npm install --global timetree-mcp
timetree-mcp

credentials の設定

macOS では Keychain の使用を強く推奨します。設定時、パスワードはターミナル上で隠して入力されるだけで、 shell history、MCP tool arguments、ソースコードに入ることはありません。

./scripts/setup_timetree_keychain.sh
timetree-credentials status

MCP は Keychain に保存された email/password を自動的に読み取ります。status は存在するかどうかのみを報告し、 値を返しません。2 つの Keychain item を削除する場合：

timetree-credentials clear

Keychain を使わない場合、環境変数でも対応できます：

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

さらに推奨されるのは、権限を 600 に設定した password file を使うことです：

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

Codex への登録

/absolute/path/to/timetree-mcp を checkout の場所に置き換えてください。同じ名前 timetree server がすでに存在する場合は、一度削除してから再度追加してください：

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

実際の password は shell history、MCP tool arguments、README やソースコードに置かないでください。

NPM wrapper を使って登録する場合は、server command を次のように変更してください：

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

ログインと読み取り

• 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

書き込み

• 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

時刻は ISO-8601 文字列または Unix milliseconds で渡せます。すべての書き込みツールには confirm: true を明示する必要があります。メンバーの招待／削除 endpoint はまだ検証されていないため、意図的に追加していません。

一部の古い calendar で TimeTree sync endpoint が -425 を返す場合、events クエリはその calendar をスキップし、skipped_calendars フィールドで報告されます。他の読み取り可能な calendars が一括で失敗することはありません。

バックグラウンド監視

• timetree_start_monitor：バックグラウンド polling（間隔 30–3600 秒）を開始します。

• timetree_monitor_status：監視状態、前回の polling、エラー、通知数を確認します。

• timetree_stop_monitor：監視を停止します。

最初の polling は baseline を構築するだけです。その後の追加・変更・削除を検出すると、server は MCP notifications/message を送信します。監視は MCP process に依存しており、client が終了すると監視も停止します。

プロジェクト構造

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

テスト

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

舊的 browser transport は互換性の予備として src/timetree_mcp/browser.py に残っていますが、server のデフォルトでは読み込まれません。

License

本プロジェクトは MIT License の下で公開されています。