TimeTree MCP

TimeTree MCP es un servidor no oficial del Model Context Protocol que accede a los calendarios de TimeTree a través de HTTPS. Por defecto usa un cliente directo de Python, sin abrir un navegador; el transporte por navegador solo se conserva como respaldo de compatibilidad. Las cookies de sesión y el token CSRF viven únicamente en la memoria del proceso MCP.

Importante: La Connect App/API oficial de TimeTree ha sido descontinuada. Este proyecto usa endpoints no públicos de TimeTree Web; pueden fallar cuando el servicio cambie de versión. Evalúa el riesgo por ti mismo y cumple con los términos y políticas de TimeTree.

Funciones

• Lee calendars, events, memos, comments, labels y members.

• Crea, actualiza y elimina events y memos.

• Añade, actualiza y elimina comentarios de eventos.

• Actualiza las etiquetas del calendario mediante una operación merge.

• Monitoriza los cambios del calendario en segundo plano y envía notificaciones MCP.

• Todas las operaciones de escritura exigen pasar confirm: true explícitamente.

• No pone las credenciales en los argumentos de las herramientas MCP; la sesión autenticada solo se guarda en memoria.

Related MCP server: TimeTree MCP Server

Requisitos

• Python 3.10 o superior.

• Cuenta de TimeTree.

• macOS para poder usar el helper de Keychain; en otras plataformas se pueden usar variables de entorno o archivo de contraseña.

Instalación

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

El runtime solo usa la biblioteca estándar de Python. Tras la instalación se ofrecen los comandos timetree-mcp y timetree-credentials.

Usar el NPM wrapper

El wrapper de NPM requiere Node.js 18+ y Python 3.10+. Inicia el servidor MCP Python incluido en el paquete y reenvía la entrada/salida estándar del MCP:

npx --yes timetree-mcp

También se puede instalar de forma global:

npm install --global timetree-mcp
timetree-mcp

Configurar credenciales

En macOS se recomienda usar Keychain. Al configurarla, la contraseña se introduce oculta en el terminal; no pasa al historial del shell, a los argumentos de MCP ni al código fuente:

./scripts/setup_timetree_keychain.sh
timetree-credentials status

El MCP lee automáticamente el email/password de Keychain. El status solo comprueba que existan, no devuelve los valores. Para eliminar los dos elementos de Keychain:

timetree-credentials clear

Si no se usa Keychain, también pueden usarse variables de entorno:

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

Es preferible usar un archivo de contraseña con permisos 600:

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

Registro en Codex

Reemplaza /absolute/path/to/timetree-mcp por la ruta de tu checkout. Si ya existe un servidor llamado timetree, elimínalo antes de volver a añadirlo:

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

No pongas la contraseña real en el historial del shell, en los argumentos de las herramientas MCP, en el README ni en el código fuente.

Si se registra con el NPM wrapper, cambia el comando del servidor a:

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

Herramientas MCP

Inicio de sesión y lectura

• 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

Escritura

• 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

Las fechas pueden pasarse como cadenas ISO-8601 o milisegundos Unix. Todas las operaciones de escritura exigen confirm: true explícito. El endpoint de invitar/eliminar miembros no está verificado, por lo que no se incluyó a propósito.

Si algunos calendarios antiguos devuelven -425 en el endpoint de sincronización de TimeTree, las consultas de events omitirán ese calendario y lo informarán en el campo skipped_calendars, sin que el resto de calendarios legibles falle por completo.

Monitorización en segundo plano

• timetree_start_monitor: inicia un polling en segundo plano con un intervalo de 30 a 3600 segundos.

• timetree_monitor_status: muestra el estado de la monitorización, el último polling, los errores y el número de notificaciones.

• timetree_stop_monitor: detiene la monitorización.

El primer polling solo establece una línea base. A partir de ahí, cuando detecta añadidos, cambios o eliminaciones, el servidor envía la notificación MCP notifications/message. La monitorización depende del proceso MCP y se detiene cuando el cliente termina.

Estructura del proyecto

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

Pruebas

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

El antiguo transporte ego-browser se conserva en src/timetree_mcp/browser.py como respaldo de compatibilidad, pero el servidor no lo carga por defecto.

Licencia

Este proyecto se distribuye bajo la MIT License.