appletv-mcp

Un servidor MCP que le da a un agente de IA control total sobre un Apple TV en la red local — sin mando, sin Siri.

Construido sobre pyatv (protocolos Companion + AirPlay). Un proyecto hermano, appletv-remote, ofrece las mismas capacidades como una habilidad de Claude Code / opencode en lugar de un servidor.

Qué puede hacer

Las herramientas de control aceptan un nombre de device opcional para apuntar a una TV no predeterminada (atv_scan, atv_devices y atv_use son las excepciones — se aplican a la configuración de emparejamiento en sí).

Configuración

Requisito previo: uv (brew install uv).

1. Empareja una vez por TV (interactivo; la TV muestra un PIN de 4 dígitos dos veces):

uv run python scripts/pair.py

Las credenciales se almacenan solo para el propietario en ~/.config/appletv-remote/devices.json (compartido con la habilidad appletv-remote). Mantén ese archivo privado — otorga control total de la TV.

No interactivo (impulsado por agente): establece ATV_PIN_FILE=/tmp/atv_pin.txt, ejecuta pair.py <name-filter> y escribe cada PIN en ese archivo.

2. Registra el servidor con tu cliente MCP. Ejemplo para opencode (~/.config/opencode/opencode.json):

"mcp": {
  "appletv": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/path/to/appletv-mcp", "python", "server.py"],
    "enabled": true
  }
}

Para Claude Code: claude mcp add appletv -- uv run --directory /path/to/appletv-mcp python server.py

Notas y advertencias

• pyatv está fijado a un commit exacto de un fork sin fusionar que corrige play_url en tvOS 26 (PR #2846, problemas #2821/#2774). Una vez fusionado y publicado, vuelve a usar el pyatv estándar.

• Los enlaces profundos de Netflix no son fiables desde su actualización de la app de tvOS de septiembre de 2025; atv_watch recurre con elegancia, y siempre puedes usar atv_launch_app("netflix") + atv_type(...).

• Las búsquedas de JustWatch usan por defecto EE. UU./en; anula con ATV_JW_COUNTRY / ATV_JW_LANGUAGE.

• Los streams de YouTube se envían como HLS vía AirPlay 2: la reproducción se pone en cola en la TV y continúa después de que la herramienta regrese. Las URLs expiran después de ~6h.

• Una advertencia de FetchAttentionState failed al conectar es inofensiva (peculiaridad del fork); los comandos siguen funcionando.

• Probado en tvOS 26 (Apple TV 4K gen 3). tvOS 13+ debería funcionar.

Licencia

MIT