appletv-mcp
A local MCP server that lets AI agents control Apple TVs over Apple's Companion/AirPlay protocols — no cloud, no remote needed.
Find & play content by name —
atv_watchsearches JustWatch and deep-links into a movie/show on a chosen service (Netflix, Disney+, Apple TV+, Max, Hulu, Prime).Play any video URL —
atv_playhandles direct media (.mp4,.m3u8) or ~1,800 yt-dlp-supported sites via AirPlay;atv_youtubeplays YouTube by URL, ID, or search terms.Open deep links —
atv_open_urlroutes app-specific URLs (Apple TV+, Disney+, Max, Hulu, Prime, YouTube) to the right app.Remote / navigation —
atv_remotepresses buttons (arrows, select, menu, home, play/pause, next/previous, volume, suspend, wakeup).Text input —
atv_typetypes into the focused on-screen field (e.g. a search box).Apps —
atv_launch_applaunches by friendly name or bundle ID;atv_list_appslists installed apps.Status —
atv_now_playingreports title, artist/app, position, and playback state.Power —
atv_powersleeps (HDMI-CEC off) or wakes the TV.Multi-TV management —
atv_deviceslists paired TVs,atv_usesets the default,atv_scanfinds TVs on the network; control tools accept an optionaldeviceargument to target a non-default TV.
Note: the README advertises 18 tools, but this schema exposes 13 — the audio tools (atv_volume, atv_audio_outputs, atv_repeat, atv_shuffle) and atv_seek are missing here, and atv_remote's documented 26 buttons are narrowed to ~17 in the schema description.
Provides full control of an Apple TV over the local network, including remote control, launching apps, typing, power management, and streaming media via AirPlay.
Supports deep linking to Netflix titles and launching the Netflix app on the Apple TV, with a fallback to manual typing for search due to unreliable deep links.
Supports deep linking to Amazon Prime Video titles via JustWatch search and launching the Prime Video app on the Apple TV.
Allows playing any YouTube video by URL or plain search terms, streaming it to the Apple TV via AirPlay, optionally inside the YouTube app.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@appletv-mcp Pull up Severance on the living room TV"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
"Watch Severance." — resolves the title via JustWatch, deep-links straight into the episode on Apple TV+.
"Put the new Veritasium video on the TV." — finds it on YouTube and plays it full-screen via AirPlay.
"Turn the volume down and pause." — done.
No remote. No Siri. No cloud. Everything runs on your local network over Apple's own protocols, powered by pyatv.
"Please play Severance season 2 episode 1 on the TV."
Why this one
appletv-mcp | mcp-pyatv | mcp-tv | Home Assistant | |
"Watch <title>" by name (JustWatch → deep link) | ✅ | ❌ | ❌ | manual URLs |
Play any video URL / ~1,800 sites (yt-dlp → AirPlay) | ✅ | ❌ | ❌ | ❌ |
YouTube by search terms | ✅ | ❌ | ❌ | ❌ |
Deep links into titles (Apple TV+, Disney+, Max, Hulu, …) | ✅ | ❌ | ❌ | manual |
App deep-link catalog in docs | ✅ | ❌ | ❌ | partial |
Absolute volume 0–100, seek, repeat, shuffle | ✅ | ❌ | ❌ | partial |
AirPlay audio output routing (HomePods) | ✅ | ❌ | ❌ | ❌ |
Multi-TV with per-tool targeting + self-healing IPs | ✅ | ❌ | ❌ | partial |
tvOS 26 AirPlay video push that actually works | ✅ (fork pin) | ❌ | ❌ | ❌ |
No always-on automation stack required | ✅ | ✅ | ✅ | ❌ |
Companion skill for non-MCP agents | ❌ | ❌ | ❌ |
Related MCP server: apple-music
Quickstart
Prerequisite: uv (brew install uv).
1. Pair (once per TV; the TV shows a 4-digit PIN twice):
git clone https://github.com/slandau3/appletv-mcp.git && cd appletv-mcp
uv run python scripts/pair.pyCredentials live owner-only (0600) in ~/.config/appletv-remote/devices.json,
shared with the appletv-remote
skill. Keep that file private — it grants full control of the TV.
2. Register with your MCP client:
Claude Code:
claude mcp add appletv -- uv run --directory /path/to/appletv-mcp python server.pyopencode (~/.config/opencode/opencode.json):
{
"mcp": {
"appletv": {
"type": "local",
"command": ["uv", "run", "--directory", "/path/to/appletv-mcp", "python", "server.py"],
"enabled": true
}
}
}Tools (18)
Content discovery & playback
Tool | What it does |
| Find a movie/show by name (JustWatch) and deep-link straight into it. Optional |
| Play ANY video URL in the native system player: direct media (.mp4/.m3u8/...) or ~1,800 sites via yt-dlp (Vimeo, Dailymotion, Twitch, X, news embeds). No DRM services |
| Play a YouTube video by URL, ID, or plain search terms. |
| Open any deep link; tvOS routes it to the right app |
Remote & navigation
Tool | What it does |
| 26 buttons: arrows, select, menu, home, top_menu, home_hold, control_center, guide, screensaver, play/pause/play_pause/stop/next/previous, skip_forward/backward, channel up/down, volume up/down, suspend, wakeup |
| Type into the focused on-screen field (optional |
| Seek to a position in seconds |
Audio
Tool | What it does |
| Get volume, step up/down, or set absolute 0–100 |
| List AirPlay audio outputs (HomePods) or route audio to one |
| Repeat (off/track/all) and shuffle (off/songs/albums) |
Apps & system
Tool | What it does |
| Launch by friendly name (netflix, disney+, max, hulu, prime video, peacock, paramount+, plex, spotify, …) or bundle id; list installed apps |
| Title, artist, frontmost app, position, playback state |
| Sleep/wake (HDMI-CEC turns the TV off too) |
| Multi-TV management: list paired TVs, set the default, scan the network |
Control tools accept an optional device name to target a non-default TV.
How it works
pyatv speaks Apple's Companion protocol (remote buttons, apps, keyboard, deep links, text input) and AirPlay 2 (video push, volume, output routing). Pairing happens once via on-screen PIN; after that, every tool call is a local, encrypted, no-cloud interaction. When a TV's IP changes, the server re-finds it by its stable identifier and updates the config itself.
Notes
pyatv is pinned to an exact commit of an unmerged fork fixing
play_urlon tvOS 26 (PR #2846, issues #2821/#2774). Once merged and released, we'll switch back to stock pyatv.Netflix deep links are unreliable since its Sept 2025 tvOS app update;
atv_watchreports availability and you can fall back toatv_launch_app("netflix")+atv_type(...).Some sites (e.g. Vimeo) bot-block yt-dlp extraction with a 403 — AirPlay from a phone/browser is the fallback.
JustWatch lookups default to US/en; override with
ATV_JW_COUNTRY/ATV_JW_LANGUAGE.Streamed URLs are IP-bound and expire (~6h) — always resolve fresh.
Tested on tvOS 26 (Apple TV 4K gen 3). tvOS 13+ should work.
Contributing
Issues and PRs welcome. The codebase is one readable file
(server.py, ~700 lines) plus a pairing script — easy to hack on.
License
MIT — see LICENSE.
Available Tools
13 toolsatv_devicesA
List paired Apple TVs and which is the default.
Inputs: no named parameters. Returns: result
atv_launch_appC
Launch an app by friendly name (netflix, youtube, disney+, max, hulu, prime video, peacock, paramount+, plex, spotify, tv, music, settings, app store, ...) or by bundle identifier.
Inputs: app (required), device. Returns: result
atv_list_appsB
List apps installed on the Apple TV (name + bundle identifier).
Inputs: device. Returns: result
atv_now_playingC
What is currently playing: title, artist/app, position, and state.
Inputs: device. Returns: result
atv_open_urlA
Open a deep link on the Apple TV; tvOS routes it to the app that claims it. The way to pull up a specific movie or episode directly. Working shapes: https://tv.apple.com/us/show|movie|episode/... (Apple TV+), https://www.disneyplus.com/video/, https://play.hbomax.com/ page/urn:hbo:page:, https://www.hulu.com/watch/, https://watch.amazon.com/detail?gti=, youtube://www.youtube.com/ watch?v= (may show a confirmation a human must accept). Netflix links are unreliable since its Sept 2025 app update.
Inputs: url (required), device. Returns: result
atv_playA
Play any video URL on the TV in the native system player: direct media files (.mp4, .m3u8, .mov, ...) or a video page from any site yt-dlp supports (~1800: Vimeo, Twitch, X, news sites, most embed players). The stream is extracted, then queued on the TV via AirPlay — playback continues after the tool returns. DRM-protected services (Netflix, Disney+, ...) cannot be extracted; use atv_watch or atv_open_url for those.
Inputs: url (required), device. Returns: result
atv_powerB
Power control: 'sleep' (turns off TV/AVR via HDMI-CEC) or 'wake'.
Inputs: action (required), device. Returns: result
atv_remoteA
Press a remote-control button. One of: up, down, left, right, select, menu (back), home, play, pause, play_pause, stop, next, previous, volume_up, volume_down, suspend (sleep), wakeup. Never blind-press buttons to 'confirm a dialog' — you cannot see the TV screen.
Inputs: action (required), device. Returns: result
atv_scanA
Scan the network for Apple TVs (name, model, address).
Inputs: no named parameters. Returns: result
atv_typeB
Type text into the focused on-screen text field (e.g. a search box). The field must already be focused on screen.
Inputs: text (required), device. Returns: result
atv_useC
Set the default Apple TV used when no device is specified.
Inputs: name (required). Returns: result
atv_watchA
Find a movie or show and pull it up on the Apple TV. Searches JustWatch, picks the deep link for the requested service (e.g. 'netflix', 'disney+', 'apple tv', 'max', 'hulu', 'prime'), and opens it. Without a service, picks the first subscription-streaming offer. Region: ATV_JW_COUNTRY/ATV_JW_LANGUAGE env vars (default US/en).
Inputs: title (required), device, service. Returns: result
atv_youtubeA
Play a YouTube video on the TV. Accepts a URL (watch, youtu.be, shorts, embed, live), an 11-character video id, or plain search terms (the top result plays). By default plays full-screen in the system player via AirPlay. Set app=True to open in the YouTube app instead — tvOS may then show an 'Open in YouTube' confirmation that a human must accept with the physical remote.
Inputs: query (required), app, device. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target distinct actions: remote button presses, launching apps, opening deep links, searching for media, playing YouTube, playing arbitrary URLs, typing, power, and device management. Minor overlap exists between atv_remote's suspend/wakeup buttons and atv_power, and between atv_watch and atv_open_url, but the descriptions make the intended use clear.
All tools share the atv_ prefix and use lowercase snake_case, which gives the set a strong sense of consistency. However, naming patterns vary: some are bare verbs (atv_watch, atv_play, atv_type, atv_use) while others are nouns (atv_remote, atv_power, atv_devices), so the style is not perfectly uniform.
13 tools is a well-scoped set for an Apple TV control server. Each tool covers a meaningful part of the device control workflow without redundancy bloating the surface.
The server covers the full practical command surface for an Apple TV: discovering and selecting devices, remote control, app launching, deep-link opening, media search/playback, YouTube playback, typing, now-playing status, and power control. There are no obvious dead ends or missing core operations.
Maintenance
Related MCP Connectors
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Yeelight device discovery, state, control, and scene execution.
Control a Loxone Miniserver smart home: lights, blinds, climate, scenes and energy.
Control your Tesla - wake it, warm it up, unlock and more. Get your developer token at https://Infoseek.ai/mcp. Also requires your own Tesla developer token which is tied to your car/fleet.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling Apple TV, HomePod, and AirPlay devices via pyatv, offering 32 tools for playback, navigation, volume, apps, and more.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables control of Apple Music on macOS, including playback, track info, volume, and more.14 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables discovering, pairing with, and controlling Samsung Tizen TVs on a local network.2 npmMIT
- AlicenseCqualityBmaintenanceLets MCP agents control an Apple TV through plain-English commands, including power, playback, app launching, navigation, settings changes, and screen/UI observations via an optional WebDriverAgent helper.6MIT