The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Apple TV MCP listing page.
Open apps, navigate tvOS, control playback, type searches, adjust volume, manage power, and take screenshots so a multimodal agent can actually inspect what happened.
Apple TV MCP turns your Apple TV into a locally controlled, visually observable device for MCP-capable AI agents.
No hosted backend. No custom Apple TV app. No cloud account.
Most Apple TV automation is blind.
A script can press Right or Select, but it usually has no idea what appeared on the screen afterward.
Apple TV MCP combines semantic control with point-in-time visual observation.
| Traditional Apple TV automation | Apple TV MCP |
|---|---|
| Send blind remote commands | Take screenshots between actions |
| Build app-specific scripts | Navigate arbitrary tvOS interfaces |
| Guess whether an action worked | Inspect the screen and verify |
| Custom integration per AI system | Standard MCP tool interface |
| Remote commands only | Apps, playback, text, power, volume, navigation, and vision |
The result is a feedback loop an AI agent can actually use:
Semantic tools are still preferred whenever possible. Screenshots make the difference when the task requires navigating an interface that does not expose a direct API.
Apple TV MCP requires Python 3.14.
Or:
Then pair your Apple TV:
Configure Apple TV MCP:
Check the setup:
And start the MCP server:
Apple TV MCP exposes fourteen tools grouped around what an agent actually wants to accomplish.
Remote navigation is intentionally treated as non-idempotent. Apple TV MCP does not blindly replay navigation commands after an uncertain connection failure.
Type directly into a focused tvOS text field.
This is useful for:
Power operations use different retry semantics so a reconnect attempt cannot accidentally wake a device immediately after a successful power-off command.
The optional screenshot backend is what makes Apple TV MCP more than a remote control.
The MCP tool:
returns the current Apple TV screen as native MCP image content.
That means a multimodal MCP client can call the tool and inspect the returned image directly.
For example:
The model does not need access to a local screen.png path and does not receive base64 inside a text response.
The PNG itself is returned through MCP.
Apple TV MCP does not continuously watch the screen.
A screenshot describes what was rendered at the moment it was captured.
If the agent performs another action afterward, the previous screenshot may already be stale.
The intended pattern is:
Screenshot support is optional.
Apple TV control continues to work normally without it.
Install the separate helper:
The screenshot system uses a separate Apple developer / RemoteXPC pairing from the pairing used by pyatv.
Pair for developer access:
Then configure the screenshot helper for one Apple TV:
Verify everything together:
A healthy installation will report both Apple TV control and screen capture.
The screenshot helper has its own configuration, dependencies, and lifecycle. pymobiledevice3 is not imported by the main appletv-mcp package.
For deeper screenshot setup and transport troubleshooting, see:
The complete happy path is:
Apple TV MCP uses local stdio MCP transport.
Any MCP client capable of launching a local stdio server can use it.
A typical configuration looks like:
If Apple TV MCP is running from a cloned repository instead:
The server does not expose an HTTP endpoint and does not require OAuth.
| Tool | Purpose |
|---|---|
apple_tv_status | Read structured device and playback state |
apple_tv_capabilities | Inspect normalized feature availability |
apple_tv_list_apps | List launchable applications |
apple_tv_power | Turn the Apple TV on or off |
apple_tv_open_app | Open an application |
apple_tv_open_url | Open a URL or deep link |
apple_tv_press | Press Apple TV remote buttons |
apple_tv_playback | Control playback |
apple_tv_seek | Seek to an absolute playback position |
apple_tv_skip | Skip forward or backward |
apple_tv_set_text | Replace focused keyboard text |
apple_tv_set_volume | Set an absolute volume |
apple_tv_adjust_volume | Adjust volume relatively |
apple_tv_screenshot | Return one screenshot as MCP image content |
The screenshot tool is the only tool that returns image content rather than a structured result.
Apple TV MCP keeps control and visual observation intentionally separate.
Apple TV control is provided through pyatv.
Apple TV MCP adds a semantic application layer on top for:
The stable Apple TV identifier is authoritative.
The last known IP address is only an optimization. If the Apple TV changes addresses, Apple TV MCP can rediscover it by identifier and update the preferred host.
Screenshots use the separate appletv-screenshot helper.
The helper uses pymobiledevice3 to reach Apple's developer services over RemoteXPC and request a screenshot through DVT.
Its default transport strategy is:
The normal Wi-Fi userspace path does not require root or a permanently running tunnel daemon.
The helper exists as a separate process so its protocol stack, dependencies, pairing records, and failure modes remain isolated from Apple TV control.
pymobiledevice3 is confined to the separately distributed appletv-screenshot helper. The main appletv-mcp package does not import or bundle it; the two processes communicate through a narrow command-line/file contract.
The MCP interface intentionally exposes semantic operations rather than raw Apple protocols.
An agent should think:
not:
When a semantic operation exists, use it.
Visual navigation is the fallback for interfaces that require it.
Apple TV MCP is designed to remain local.
Debug mode also keeps raw pyatv protocol logging disabled because low-level Companion traffic can contain sensitive keyboard and pairing payloads.
Streaming applications may protect video using DRM.
In that case, screenshots can contain:
while menus or playback controls remain visible.
That is expected.
Apple TV MCP does not interpret a black protected video region as proof that:
and it does not attempt to bypass DRM.
Apple TV MCP intentionally has a narrow initial scope.
Each server configuration controls one Apple TV.
Multi-device routing is not currently part of the public MCP interface.
apple_tv_screenshot captures one frame at a time.
There is no:
pyatv does not provide a universal signal for the currently highlighted tvOS element.
An agent can use screenshots to infer focus where appropriate.
media_app is not foreground_appApple TV status may identify the application associated with current media metadata.
That does not independently guarantee which application is visually in the foreground.
Screenshot support relies on Apple developer protocols exposed through pymobiledevice3.
tvOS changes may require future compatibility updates.
Every non-screenshot Apple TV MCP tool works without the screenshot helper installed.
Apple TV MCP stores application configuration in the platform-standard config directory.
Typical settings include:
Pairing credentials are not stored in this file.
If an MCP host launches processes with a minimal PATH, set screen_capture.command to the absolute path of the screenshot helper.
Existing configuration files from Apple TV MCP v0.1 remain compatible.
Run:
to diagnose the complete installation.
It checks areas such as:
Screenshot support is optional.
If the helper is not installed, Doctor reports it as skipped rather than treating Apple TV control as broken.
Confirm:
atvremote wizard completed successfullyThen rerun:
That is expected.
Apple TV MCP identifies the configured device by its stable identifier rather than trusting an old IP address.
Use:
to see the applications currently exposed by the device.
Application-name matching is deterministic rather than fuzzy.
A text field must already be focused on the Apple TV.
Install it:
or configure Apple TV MCP with its absolute path.
Run:
Developer screenshot pairing is separate from atvremote.
Run:
Protected content may intentionally hide its video frame.
Try opening a tvOS menu or application interface and capture again.
Clone the repository:
Install:
Run the complete root quality gate:
The screenshot helper is a separate Python project:
The root package deliberately does not depend on or bundle pymobiledevice3.
Normal tests use fakes and do not require Apple hardware.
Read-only Apple TV integration tests are explicitly opt-in:
Tests that can change Apple TV state require an additional opt-in:
Never enable the live-write suite against a device you do not intend to control.
Contributions are welcome.
Before opening a pull request:
If your change affects the screenshot helper, run its independent quality gate as well.
Please preserve the project's core architecture:
Avoid exposing raw Apple protocol details through the MCP contract unless there is a clear semantic reason.
This repository contains two separately distributed components.
appletv-mcp is licensed under the MIT License.
It does not import, bundle, or distribute pymobiledevice3.
The optional appletv-screenshot helper under
sidecars/appletv-screenshot/ is licensed under GPL-3.0-or-later.
The helper directly uses pymobiledevice3, which is also licensed
under GPL-3.0-or-later.
The two components communicate through a one-shot subprocess interface.
See LICENSING.md for the repository-wide map.
AI agents are much more useful when they can verify the effects of their actions.
Apple TV MCP gives them both sides of that loop:
So instead of blindly pressing buttons, an agent can interact with tvOS, inspect the result, and decide what to do next.