appletv-mcp

An MCP server that gives an AI agent full control of an Apple TV over the local network — no remote, no Siri.

Built on pyatv (Companion + AirPlay protocols). A sibling project, appletv-remote, provides the same capabilities as a Claude Code / opencode skill instead of a server.

What it can do

Control tools accept an optional device name to target a non-default TV (atv_scan, atv_devices, and atv_use are the exceptions — they apply to the pairing config itself).

Setup

Prerequisite: uv (brew install uv).

1. Pair once per TV (interactive; the TV shows a 4-digit PIN twice):

   uv run python scripts/pair.py
   

   Credentials are stored owner-only in ~/.config/appletv-remote/devices.json (shared with the appletv-remote skill). Keep that file private — it grants full control of the TV.

   Non-interactive (agent-driven): set ATV_PIN_FILE=/tmp/atv_pin.txt, run pair.py <name-filter>, and write each PIN to that file.

2. Register the server with your MCP client. Example for opencode (~/.config/opencode/opencode.json):

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

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

Notes and caveats

• pyatv is pinned to an exact commit of an unmerged fork fixing play_url on tvOS 26 (PR #2846, issues #2821/#2774). Once merged and released, switch back to stock pyatv.
• Netflix deep links are unreliable since its Sept 2025 tvOS app update; atv_watch falls back gracefully, and you can always atv_launch_app("netflix") + atv_type(...).
• JustWatch lookups default to US/en; override with ATV_JW_COUNTRY / ATV_JW_LANGUAGE.
• YouTube and atv_play streams are pushed as HLS via AirPlay 2: playback is queued on the TV and continues after the tool returns. URLs expire after ~6h. Some sites (e.g. Vimeo) block yt-dlp extraction with a 403 — AirPlay from a phone/browser is the fallback.
• A FetchAttentionState failed warning at connect time is benign (fork quirk); commands still work.
• Tested on tvOS 26 (Apple TV 4K gen 3). tvOS 13+ should work.

License

MIT