Apple TV MCP

Apple TV MCP: A local MCP server that lets AI agents control — and see — your Apple TV

Open apps, navigate tvOS, control playback, type searches, adjust volume, manage power, and take screenshots so a multimodal agent can actually inspect what happened.

You:

Open YouTube and search for OpenAI.

Agent: → opens YouTube → takes a screenshot → sees the current interface → navigates to Search → types "OpenAI" → takes another screenshot → verifies the results

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.

---

Why Apple TV MCP?

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.

The result is a feedback loop an AI agent can actually use:

screenshot

↓ model sees tvOS ↓ chooses an action ↓ press / type / open ↓ screenshot again ↓ verify

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.

---

Install in seconds

Apple TV MCP requires Python 3.14.

Recommended

uv tool install appletv-mcp

Or:

pipx install appletv-mcp

Then pair your Apple TV:

atvremote wizard

Configure Apple TV MCP:

appletv-mcp configure

Check the setup:

appletv-mcp doctor

And start the MCP server:

appletv-mcp serve

From source

git clone https://github.com/trevor-nichols/appletv-mcp.git

cd appletv-mcp uv sync --locked uv run appletv-mcp configure uv run appletv-mcp doctor uv run appletv-mcp serve

---

What can it do?

Apple TV MCP exposes fourteen tools grouped around what an agent actually wants to accomplish.

See

• Take a screenshot of the current Apple TV screen
• Read device, connection, playback, and media state
• Inspect available Apple TV capabilities

Apps

• List installed applications
• Open an application by name
• Open an application by bundle identifier
• Open deep links and custom application URLs

Navigate

• Up
• Down
• Left
• Right
• Select
• Back
• Home
• Menu
• Other supported remote actions

Remote navigation is intentionally treated as non-idempotent. Apple TV MCP does not blindly replay navigation commands after an uncertain connection failure.

Playback

• Play
• Pause
• Toggle play/pause
• Stop
• Next
• Previous
• Seek to an absolute position
• Skip forward or backward

Text

Type directly into a focused tvOS text field.

This is useful for:

• Search
• Usernames
• App navigation
• Query entry

Volume

• Read volume when available
• Set an absolute volume level
• Adjust volume relatively

Power

• Turn the Apple TV on
• Turn the Apple TV off

Power operations use different retry semantics so a reconnect attempt cannot accidentally wake a device immediately after a successful power-off command.

---

Give your agent eyes

The optional screenshot backend is what makes Apple TV MCP more than a remote control.

The MCP tool:

apple_tv_screenshot

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:

Agent:

apple_tv_screenshot()

→ sees the Apple TV Home Screen → sees YouTube highlighted

apple_tv_press(button="select")

apple_tv_screenshot()

→ sees the YouTube interface

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.

Screenshots are point-in-time

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:

observe

→ act → observe → verify

---

Enable screenshots

Screenshot support is optional.

Apple TV control continues to work normally without it.

Install the separate helper:

uv tool install appletv-screenshot

The screenshot system uses a separate Apple developer / RemoteXPC pairing from the pairing used by pyatv.

Pair for developer access:

pymobiledevice3 remote pair

Then configure the screenshot helper for one Apple TV:

appletv-screenshot configure --udid <UDID>

Verify everything together:

appletv-mcp doctor

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:

sidecars/appletv-screenshot/README.md

---

Quick start

The complete happy path is:

# Install

uv tool install appletv-mcp

Pair for Apple TV control

atvremote wizard

Choose the Apple TV

appletv-mcp configure

Optional: install visual observation

uv tool install appletv-screenshot

Optional: developer pairing for screenshots

pymobiledevice3 remote pair appletv-screenshot configure --udid

Verify

appletv-mcp doctor

Run the MCP server

appletv-mcp serve

---

Connect your MCP client

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:

{

"mcpServers": { "appletv-mcp": { "command": "appletv-mcp", "args": ["serve"] } } }

If Apple TV MCP is running from a cloned repository instead:

{

"mcpServers": { "appletv-mcp": { "command": "uv", "args": [ "--directory", "/absolute/path/to/appletv-mcp", "run", "appletv-mcp", "serve" ] } } }

The server does not expose an HTTP endpoint and does not require OAuth.

---

Tools

The screenshot tool is the only tool that returns image content rather than a structured result.

---

How it works

Apple TV MCP keeps control and visual observation intentionally separate.

                         AI Agent

│ ▼ Apple TV MCP / \ / \ ▼ ▼ semantic control screen capture │ │ pyatv appletv-screenshot │ │ │ pymobiledevice3 │ │ │ RemoteXPC / DVT │ │ └──── Apple TV ─┘

Control

Apple TV control is provided through pyatv.

Apple TV MCP adds a semantic application layer on top for:

• deterministic app resolution
• capability checking
• connection lifecycle
• safe retry behavior
• non-idempotent command protection
• normalized MCP results

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.

Vision

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:

macOS:

native → userspace → tunneld

Linux / Windows: userspace → tunneld

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.

---

Designed for agents

The MCP interface intentionally exposes semantic operations rather than raw Apple protocols.

An agent should think:

open YouTube

pause playback seek to 2:00 type "Severance" set volume to 35% take a screenshot

not:

send Companion command

call MRP endpoint construct RemoteXPC request

When a semantic operation exists, use it.

Visual navigation is the fallback for interfaces that require it.

---

Privacy and security

Apple TV MCP is designed to remain local.

• No hosted Apple TV MCP backend
• No cloud account
• MCP uses local stdio transport
• Apple TV pairing credentials stay on the user's machine
• RemoteXPC pairing records stay with the screenshot helper
• Credentials are never MCP parameters
• Credentials are never returned to the model
• Keyboard text is not emitted into normal logs
• Screenshots are captured only when explicitly requested
• Screenshot bytes are not logged
• Screenshots are stored only in a private temporary directory during capture
• Temporary screenshot files are deleted after the MCP result is created
• Screenshot capture does not run automatically after commands
• The helper is launched without a shell
• No DRM circumvention is attempted

Debug mode also keeps raw pyatv protocol logging disabled because low-level Companion traffic can contain sensitive keyboard and pairing payloads.

---

Protected video

Streaming applications may protect video using DRM.

In that case, screenshots can contain:

black video

blank video redacted video

while menus or playback contro