TimeTree MCP

TimeTree MCPは非公式の Model Context Protocol server로, HTTPS를 통해 TimeTree 캘린더에 접근할 수 있습니다. 기본적으로 Python direct client를 사용하며 브라우저를 실행하지 않습니다. browser transport는 호환성 fallback으로만 유지됩니다. session cookie와 CSRF token은 MCP process 메모리에만 존재합니다.

중요: TimeTree 공식 Connect App/API는 종료되었습니다. 이 프로젝트는 TimeTree Web의 비공개 endpoint를 사용하므로 서비스가 개편되면 동작하지 않을 수 있습니다. 위험은 직접 평가하고 TimeTree의 약관과 정책을 준수하세요.

기능

• 캘린더, 이벤트, 메모, 댓글, 라벨, 멤버를 조회합니다.

• 이벤트와 메모를 생성, 업데이트, 삭제합니다.

• 이벤트 댓글을 추가, 업데이트, 삭제합니다.

• 캘린더 라벨을 merge 방식으로 업데이트합니다.

• 캘린더 변경 사항을 백그라운드에서 모니터링하고 MCP notifications을 전송합니다.

• 모든 쓰기 작업에는 confirm: true를 명시적으로 전달해야 합니다.

• 자격 증명을 MCP tool arguments에 넣지 않으며, 인증된 세션은 메모리에만 저장됩니다.

Related MCP server: TimeTree MCP Server

요구 사항

• Python 3.10 또는 그 이상.

• TimeTree 계정.

• macOS에서만 Keychain helper를 사용할 수 있습니다. 다른 플랫폼에서는 환경 변수나 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+가 필요합니다. it is 시작합니다. 패키지에 포함된 Python MCP server를 시작하고 MCP의 stdin/stdout을 전달합니다.

npx --yes timetree-mcp

전역 설치도 가능합니다.

npm install --global timetree-mcp
timetree-mcp

자격 증명 설정

macOS에서는 Keychain을 권장합니다. 설정 시 비밀번호는 터미널에서 숨겨진 입력으로 입력되며, shell history나 MCP arguments, 소스 코드에 남지 않습니다.

./scripts/setup_timetree_keychain.sh
timetree-credentials status

MCP는 Keychain에서 email/password를 자동으로 읽습니다. status는 존재 여부만 알려주며 값을 반환하지 않습니다. Keychain 항목 두 개를 삭제하려면:

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(밀리초)로 전달할 수 있습니다. 모든 쓰기 tools에는 confirm: true를 명시적으로 전달해야 합니다. 멤버 초대·제거 endpoint는 아직 검증되지 않아 의도적으로 포함하지 않았습니다.

일부 오래된 calendar의 TimeTree sync endpoint가 -425를 반환하면 events 조회는 해당 calendar를 건너뛰고 skipped_calendars 필드로 보고됩니다. 다른 읽기 가능한 calendar 전체가 실패하지는 않습니다.

백그라운드 모니터링

• 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

이전 ego-browser transport는 src/timetree_mcp/browser.py에 호환성 fallback으로 남아 있지만, server는 기본적으로 이를 로드하지 않습니다.

라이선스

이 프로젝트는 MIT License를 사용합니다.