TimeTree MCP

TimeTree MCP — это неофициальный Model Context Protocol сервер для доступа к календарям TimeTree через HTTPS. По умолчанию используется прямой Python-клиент, браузер не запускается; browser transport сохранён только как совместимый резервный вариант. Session cookie и CSRF token существуют только в памяти процесса MCP.

Важно: официальный Connect App/API TimeTree прекращён. Этот проект использует непубличный endpoint веб-версии TimeTree, который может перестать работать при изменении сервиса. Оценивайте риски самостоятельно и соблюдайте условия и политику TimeTree.

Возможности

• Чтение calendars, events, memos, comments, labels и members.

• Создание, обновление и удаление events и memos.

• Добавление, обновление и удаление comments к событиям.

• Обновление labels календаря через merge.

• Фоновый мониторинг изменений calendar и отправка MCP notifications.

• Все операции записи требуют явной передачи confirm: true.

• Учётные данные не передаются в tool arguments; аутентифицированная сессия хранится только в памяти.

Related MCP server: TimeTree MCP Server

Требования

• Python 3.10 или новее.

• Учётная запись TimeTree.

• Keychain для macOS; на других платформах можно использовать переменные окружения или password file.

Установка

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

Для выполнения используется только стандартная библиотека Python. После установки становятся доступны команды timetree-mcp и timetree-credentials.

Использование NPM wrapper

NPM wrapper требует Node.js 18+ и Python 3.10+; он запускает встроенный Python MCP server из состава пакета и транслирует stdin/stdout MCP:

npx --yes timetree-mcp

Можно также установить глобально:

npm install --global timetree-mcp
timetree-mcp

Настройка credentials

macOS рекомендуется использовать Keychain. При настройке пароль вводится скрыто в терминале и не попадает в shell history, аргументы MCP-инструментов или исходный код:

./scripts/setup_timetree_keychain.sh
timetree-credentials status

MCP автоматически считывает email/password из Keychain. status только сообщает о наличии, но не возвращает значения; удалить два элемента Keychain:

timetree-credentials clear

Если Keychain не используется, можно использовать переменные окружения:

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

Более рекомендуется password file с правами 600:

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 уже существует, сначала удалите его, затем добавьте:

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

Не помещайте реальный пароль в shell history, аргументы MCP-инструментов, 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 приглашения/удаления members ещё не проверен, поэтому он намеренно не включён.

Если у стариых календаря TimeTree sync endpoint возвращает -425, запрос events пропускает этот calendar и сообщает об этом в поле skipped_calendars, при этом остальные readable calendars не выдают ошибку целиком.

Фоновый мониторинг

• timetree_start_monitor: запускает фоновый polling с интервалом 30–3600 секунд.

• timetree_monitor_status: показывает статус мониторинга, время последнего polling, ошибки и количество уведомлений.

• timetree_stop_monitor: оставнавливает мониторинг.

Первый polling только создаёт baseline; далее при обнаружении добавления, изменения или удаления сервер отправляет MCP notifications/message. Мониторинг зависит от процесса MCP и останавливается после завершения клиента.

Структура проекта

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 как совместимый запасной вариант, но по умолчанию сервер его не загружает.

Лицензия

Проект использует MIT License.