CouchPilot
CouchPilot lets an agent inspect and control Apple TV devices through MCP tools.
List devices and inspect cached helper-profile expiry evidence.
Observe current app, focus, labels, values, and optionally images, with freshness checks via expected app/label.
Perform one UI action then observe: press, select, type, or launch, using observation_id for UI inputs.
Read power and now-playing metadata.
List installed apps and bundle IDs.
Use paired control to wake, sleep, transport, press buttons, open URLs, launch apps, and type text.
Allows control of an Apple TV, including power, playback, app launching, navigation, typing, and picture settings, with optional screen and UI inspection for visual tasks.
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., "@CouchPilot Find and play the next episode of Ted Lasso."
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.
🛋️ CouchPilot
Let your agent control your Apple TV.
I got sick of screwing around with Apple TV settings, hunting down shows across streaming apps, and relaying an agent’s troubleshooting advice through the remote. CouchPilot lets you ask your agent in plain English to queue up shows, change settings, and navigate apps—especially useful if using a projector + Apple TV.
“Find Breaking Bad and get an episode ready.”
“Help me fix the washed-out picture.”
“Find and install Crossy Road.”
A local, open-source bridge for Codex, Claude Code, and other MCP agents. No jailbreak. No separate model API key.
How it works
flowchart TD
You["You"] -->|"Plain English"| Agent["Your agent"]
Agent <-->|"MCP tools and results"| Bridge["CouchPilot<br/>on your computer"]
Bridge <-->|"pyatv<br/>Direct commands"| TV["Apple TV"]
Bridge <-->|"Optional WDA helper<br/>Screen and UI"| TVpyatv handles power, playback, app launches, and typing over your local network. For tasks that need the screen, a signed WebDriverAgent helper on the Apple TV returns UI labels, focus, and screenshots. Your existing agent chooses the next action and checks the result, using compact text observations first and images when needed.
Related MCP server: blade-computer-use
Why CouchPilot?
Alternatives such as Apple TV MCP use individual screenshots; CouchPilot uses a signed WDA helper for structured UI labels and focus, text-first observations, and freshness-checked actions. We’ve verified that loop on a real Apple TV. Comparison and tradeoffs →
Get started → · What works today · Architecture · MIT license
Early preview: playback, app navigation, and a picture-setting change have been tested on a real Apple TV. Full visual control currently needs a Mac and a signed helper; free signing requires occasional renewal. Cross-service show discovery and seamless setup are still works in progress.
Available Tools
6 toolsactC
Act once, then observe. UI inputs need observation_id.
Select activates a unique, already focused label without moving focus.
Inputs: value (required), action (required), device (required), role, +4 more.
appsB
List installed apps and their bundle IDs through paired control.
Inputs: device (required). Returns: object
controlD
Paired control. Use press for explicit buttons; observe agent-chosen navigation.
Inputs: device (required), operation (required), value. Returns: object
devicesC
List routes and freshly inspect local cached helper-profile expiry evidence.
Inputs: no named parameters. Returns: object
observeA
Read fresh app, focus, labels, and values. Request an image only when useful.
Inputs: device (required), image, expected_app, expected_label.
statusC
Read power and now-playing metadata through paired control; no screenshots needed.
Inputs: device (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools split into discovery (devices/apps), screen reading (observe), UI actions (act), hardware state (status), and remote presses (control). Act vs control and observe vs status have some surface overlap, but their descriptions and inputs are distinct enough for an agent to choose correctly.
All names are single lowercase words, but they mix bare nouns (devices, status, apps) with bare verbs (observe, act, control) and do not follow a predictable verb_noun pattern. The names are readable but not consistent in style.
Six tools is well-scoped for a media-device remote-control and UI-automation server. Each tool covers a distinct aspect—discovery, UI state, UI action, device status, installed apps, and button control—without bloat.
The set covers the core lifecycle of piloting a device: list devices/apps, observe the UI, act on it, check power/media status, and send remote button presses. There is no explicit app-launch or volume/media-seek operation, but agents can work around this via act/control and observe.
Related MCP Connectors
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Apple Home devices, scenes, and automations through MCP.12 npm39MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to control macOS via accessibility and screen recording, providing tools to list apps, observe UI, click, type, press keys, and scroll.MIT
- AlicenseNot gradedqualityCmaintenanceExposes native iPhone device services and UI automation through MCP, enabling agents to inspect and control trusted iPhones via a unified interface.2GPL 3.0
- AlicenseAqualityCmaintenanceEnables full control of an Apple TV over the local network, including playback, remote navigation, app launching, deep links, and power management.13MIT