appletv-mcp

Ein MCP-Server, der einem KI-Agenten die volle Kontrolle über einen Apple TV im lokalen Netzwerk gibt – ohne Fernbedienung, ohne Siri.

Basiert auf pyatv (Companion- und AirPlay-Protokolle). Ein Schwesterprojekt, appletv-remote, bietet dieselben Fähigkeiten als Claude-Code-/opencode-Skill statt als Server.

Was es kann

Steuerungswerkzeuge akzeptieren einen optionalen device-Namen, um einen nicht standardmäßigen TV anzusprechen (atv_scan, atv_devices und atv_use sind die Ausnahmen – sie gelten für die Kopplungskonfiguration selbst).

Einrichtung

Voraussetzung: uv (brew install uv).

1. Einmal pro TV koppeln (interaktiv; der TV zeigt zweimal eine 4-stellige PIN an):

uv run python scripts/pair.py

Die Anmeldedaten werden nur für den Besitzer in ~/.config/appletv-remote/devices.json gespeichert (gemeinsam mit dem appletv-remote-Skill). Halte diese Datei privat – sie gewährt volle Kontrolle über den TV.

Nicht-interaktiv (agentengesteuert): Setze ATV_PIN_FILE=/tmp/atv_pin.txt, führe pair.py <name-filter> aus und schreibe jede PIN in diese Datei.

2. Registriere den Server bei deinem MCP-Client. Beispiel für opencode (~/.config/opencode/opencode.json):

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

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

Hinweise und Einschränkungen

• pyatv ist auf einen exakten Commit eines nicht zusammengeführten Forks gepinnt, der play_url auf tvOS 26 repariert (PR #2846, Issues #2821/#2774). Sobald er zusammengeführt und veröffentlicht ist, wechsle zurück zum Standard-pyatv.

• Netflix-Deep-Links sind unzuverlässig seit dem tvOS-App-Update vom September 2025; atv_watch greift elegant darauf zurück, und du kannst jederzeit atv_launch_app("netflix") + atv_type(...) verwenden.

• JustWatch-Suchen sind standardmäßig auf US/en eingestellt; überschreibe sie mit ATV_JW_COUNTRY / ATV_JW_LANGUAGE.

• YouTube-Streams werden als HLS über AirPlay 2 übertragen: Die Wiedergabe wird auf dem TV in die Warteschlange gestellt und läuft weiter, nachdem das Tool zurückkehrt. URLs laufen nach ~6 Stunden ab.

• Eine FetchAttentionState failed-Warnung beim Verbinden ist harmlos (Eigenheit des Forks); Befehle funktionieren trotzdem.

• Getestet auf tvOS 26 (Apple TV 4K Gen 3). tvOS 13+ sollte funktionieren.

Lizenz

MIT