mcp-pyatv

MCP server for controlling Apple TV, HomePod, and AirPlay devices via pyatv.

---

What It Does

mcp-pyatv is an MCP (Model Context Protocol) server that bridges any MCP client to Apple TV, HomePod, and AirPlay devices on your local network. It wraps pyatv -- the open-source Python library that implements the actual Apple TV and AirPlay protocols -- and exposes its functionality as MCP tools.

This lets you control your devices using natural language through Claude Desktop, Claude Code, Cursor, or any other MCP-compatible client.

This project does not implement any device protocols. All protocol-level communication is handled by pyatv. mcp-pyatv is purely the MCP bridge layer.

Supported Devices

• Apple TV -- all generations, including tvOS 15+
• HomePod / HomePod Mini
• AirPort Express
• Third-party AirPlay speakers
• macOS (Music/iTunes)

Quick Start

Install

pip install mcp-pyatv

Or run directly without installing:

uvx mcp-pyatv

Claude Desktop Configuration

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "apple-tv": {
      "command": "uvx",
      "args": ["--python", "python3.13", "mcp-pyatv"]
    }
  }
}

Note: Claude Desktop may not inherit your shell's PATH. If you get a "command not found" error, use the full path to uvx (run which uvx in your terminal to find it):

{
  "mcpServers": {
    "apple-tv": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["--python", "python3.13", "mcp-pyatv"]
    }
  }
}

Local Development

If you've cloned the repo and want to run from source:

{
  "mcpServers": {
    "apple-tv": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "mcp_pyatv.server"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-pyatv/src"
      }
    }
  }
}

First Use / Pairing

On first use, just say "Pair my Apple TV" to your MCP client. The server handles the rest:

1. It scans your network and discovers devices.
2. A PIN appears on your TV screen.
3. You tell the client the PIN.
4. Credentials are stored locally and persist across sessions.

You only need to pair once per device. HomePods do not require pairing.

Available Tools

mcp-pyatv exposes 32 tools organized by category:

Discovery

Tool	Description
scan_devices	Scan the local network for Apple TV and AirPlay devices
device_info	Get detailed information about a specific device

Pairing

Tool	Description
start_pairing	Begin the pairing process with a device
finish_pairing	Complete pairing by submitting the PIN shown on screen

Playback

Tool	Description
play	Resume playback
pause	Pause playback
play_pause	Toggle play/pause
stop	Stop playback
next_track	Skip to next track
previous_track	Go to previous track
skip_forward	Skip forward by a number of seconds
skip_backward	Skip backward by a number of seconds
set_position	Seek to a specific position
set_shuffle	Set shuffle mode
set_repeat	Set repeat mode

Navigation

Tool	Description
navigate	Send remote control commands -- supports up, down, left, right, select, menu, home, top_menu with single_tap, double_tap, or hold actions

Audio

Tool	Description
get_volume	Get the current volume level
set_volume	Set volume to a specific level
volume_up	Increase volume
volume_down	Decrease volume

Apps

Tool	Description
list_apps	List all installed apps
launch_app	Launch an app by name or bundle ID

Power

Tool	Description
turn_on	Turn on the device
turn_off	Turn off / put the device to sleep
power_state	Check if the device is on or off

Keyboard

Tool	Description
set_text	Type text into a text field (e.g., search boxes)
get_text	Get the current text field contents
clear_text	Clear the current text field

Streaming

Tool	Description
play_url	Stream media from a URL to the device
stream_file	Stream a local file to the device

Media Info

Tool	Description
now_playing	Get information about what's currently playing
get_artwork	Get the artwork for the currently playing media

Example Conversations

Checking what's playing:

"What's playing on my Apple TV?"

The server calls scan_devices to find your Apple TV, then now_playing to get the current track/show info.

Launching an app:

"Open Netflix"

The server calls launch_app with the Netflix bundle ID.

Adjusting volume:

"Set the volume to 40"

The server calls set_volume with level 40.

Pairing a new device:

"Pair my Apple TV"

The server calls scan_devices, then start_pairing. A PIN appears on your TV. You say "The PIN is 1234", and the server calls finish_pairing to complete the process.

Configuration

Variable	Description	Default
MCP_PYATV_STORAGE_PATH	Override the file path where pairing credentials are stored	~/.pyatv.conf

The default credential file (~/.pyatv.conf) is shared with pyatv's atvremote CLI tool. If you've already paired devices using atvremote, mcp-pyatv will pick up those credentials automatically.

Known Limitations

• play_url broken on tvOS 26.x -- upstream pyatv issue (#2821)
• stop ignored by some apps -- YouTube and certain other apps do not respond to the stop command
• get_artwork depends on the app -- not all apps expose artwork metadata
• Same network required -- your machine must be on the same WiFi network as your devices
• set_shuffle / set_repeat -- require an active music playback queue to work
• Python 3.14 -- not currently supported due to asyncio compatibility issues in pyatv

Built On

This project is built on pyatv by Pierre Stahl -- the Python library that implements the Companion, AirPlay, RAOP, MRP, and DMAP protocols used by Apple devices. All protocol-level communication, device discovery, and pairing logic happens inside pyatv. mcp-pyatv provides only the MCP server layer on top.

For protocol details, bug reports related to device communication, or to contribute to the underlying library, visit:

• pyatv GitHub
• pyatv Documentation

License

MIT -- see LICENSE for details.