Skip to main content
Glama

🛋️ 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"| TV

pyatv 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 tools
actC

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

    C2.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers