Apple TV MCP

Apple TV MCP：一个本地 MCP 服务，让 AI Agent 能够控制并查看 Apple TV

打开应用、浏览 tvOS、控制播放、输入搜索内容、调节音量、管理电源并截取屏幕截图，让多模态 Agent 真正能够查看操作结果。

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 可将 Apple TV 变成由支持 MCP 的 AI Agent 在本地控制并可视化查看的设备。

无需托管后端。无需自定义 Apple TV 应用。无需云账户。

---

为什么选择 Apple TV MCP？

大多数 Apple TV 自动化都是盲操作。

脚本可以按下“右”或“选择”，但通常不知道随后屏幕上出现了什么。

Apple TV MCP 将语义控制与特定时刻的视觉观察结合起来。

传统 Apple TV 自动化	Apple TV MCP
发送盲目的遥控器命令	在操作之间截取屏幕截图
编写特定应用的脚本	浏览任意 tvOS 界面
猜测操作是否成功	查看屏幕并进行确认
为每个 AI 系统定制集成	标准 MCP 工具接口
仅支持遥控器命令	支持应用、播放、文本、电源、音量、导航和视觉观察

由此形成的反馈循环，AI Agent 可以真正加以利用：

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

只要可行，仍应优先使用语义工具。需要浏览未提供直接 API 的界面时，屏幕截图就能发挥关键作用。

---

几秒钟即可安装

Apple TV MCP 需要 Python 3.14。

推荐方式

uv tool install appletv-mcp

或者：

pipx install appletv-mcp

然后配对 Apple TV：

atvremote wizard

配置 Apple TV MCP：

appletv-mcp configure

检查设置：

appletv-mcp doctor

然后启动 MCP 服务：

appletv-mcp serve

从源代码安装

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

---

它能做什么？

Apple TV MCP 提供十四种工具，围绕 Agent 实际想要完成的任务进行分组。

查看

• 截取当前 Apple TV 屏幕的屏幕截图
• 读取设备、连接、播放和媒体状态
• 检查 Apple TV 支持的功能

应用

• 列出已安装的应用
• 按名称打开应用
• 按应用包标识符打开应用
• 打开深层链接和自定义应用 URL

导航

• 向上
• 向下
• 向左
• 向右
• 选择
• 返回
• 主屏幕
• 菜单
• 其他受支持的遥控操作

遥控器导航被有意视为非幂等操作。连接意外中断时，Apple TV MCP 不会盲目重放导航命令。

播放

• 播放
• 暂停
• 切换播放／暂停
• 停止
• 下一首
• 上一首
• 跳转到指定位置
• 快进或快退

文本

直接在获得焦点的 tvOS 文本字段中输入内容。

适用于：

• 搜索
• 用户名
• 应用导航
• 输入查询内容

音量

• 在可用时读取音量
• 设置绝对音量
• 相对调节音量

电源

• 打开 Apple TV
• 关闭 Apple TV

电源操作采用不同的重试策略，避免在成功执行关机命令后，重连尝试意外唤醒设备。

---

让 Agent 拥有视觉能力

可选的屏幕截图后端让 Apple TV MCP 不再只是遥控器。

MCP 工具：

apple_tv_screenshot

会将当前 Apple TV 屏幕作为原生 MCP 图像内容返回。

这意味着多模态 MCP 客户端可以调用该工具，并直接查看返回的图像。

例如：

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

模型无需访问本地的 screen.png 路径，也不会在文本响应中收到 base64 数据。

PNG 图像本身通过 MCP 返回。

截图是特定时刻的记录

Apple TV MCP 不会持续监看屏幕。

截图描述的是拍摄时呈现的内容。

如果 Agent 随后执行了其他操作，之前的截图可能已经过时。

预期的使用模式是：

observe
→ act
→ observe
→ verify

---

启用截图

截图支持是可选的。

不启用截图也能正常控制 Apple TV。

安装单独的辅助工具：

uv tool install appletv-screenshot

截图系统使用单独的 Apple 开发者 / RemoteXPC 配对，与 pyatv 使用的配对不同。

为开发者访问进行配对：

pymobiledevice3 remote pair

然后为一台 Apple TV 配置截图辅助工具：

appletv-screenshot configure --udid <UDID>

一起验证所有功能：

appletv-mcp doctor

正常安装后会同时报告 Apple TV 控制和屏幕捕获功能。

截图辅助工具有自己的配置、依赖项和生命周期。主 appletv-mcp 包不会导入 pymobiledevice3。

如需深入了解截图设置和传输故障排查，请参阅：

sidecars/appletv-screenshot/README.md

---

快速开始

完整的顺利流程如下：

# 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 <UDID>

# Verify
appletv-mcp doctor

# Run the MCP server
appletv-mcp serve

---

连接 MCP 客户端

Apple TV MCP 使用本地 stdio MCP 传输。

任何能够启动本地 stdio 服务的 MCP 客户端都可以使用它。

典型配置如下：

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

如果 Apple TV MCP 是从克隆的代码库运行的，则配置如下：

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

该服务不提供 HTTP 端点，也不需要 OAuth。

---

工具

工具	用途
apple_tv_status	读取结构化的设备和播放状态
apple_tv_capabilities	检查规范化的功能可用性
apple_tv_list_apps	列出可启动的应用
apple_tv_power	打开或关闭 Apple TV
apple_tv_open_app	打开应用
apple_tv_open_url	打开 URL 或深层链接
apple_tv_press	按下 Apple TV 遥控器按钮
apple_tv_playback	控制播放
apple_tv_seek	跳转到指定的绝对播放位置
apple_tv_skip	向前或向后跳过
apple_tv_set_text	替换当前聚焦的键盘文本
apple_tv_set_volume	设置绝对音量
apple_tv_adjust_volume	相对调整音量
apple_tv_screenshot	以 MCP 图像内容形式返回一张截图

截图工具是唯一返回图像内容而非结构化结果的工具。

---

工作原理

Apple TV MCP 有意将控制与视觉观察分开。

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

控制

Apple TV 控制通过 pyatv 提供。

Apple TV MCP 在其上添加了语义应用层，用于：

• 确定性地解析应用
• 检查功能可用性
• 管理连接生命周期
• 安全重试
• 防止执行非幂等命令
• 规范化 MCP 结果

稳定的 Apple TV 标识符具有权威性。

最后已知的 IP 地址仅用于优化。如果 Apple TV 更改了地址，Apple TV MCP 可以通过标识符重新发现它，并更新首选主机。

愿景

截图使用独立的 appletv-screenshot 辅助程序。

该辅助程序使用 pymobiledevice3，通过 RemoteXPC 访问 Apple 的开发者服务，并通过 DVT 请求截图。

其默认传输策略为：

macOS:
native → userspace → tunneld

Linux / Windows:
userspace → tunneld

常规的 Wi-Fi 用户态路径不需要 root 权限，也不需要持续运行的隧道守护进程。

该辅助程序作为独立进程运行，以便其协议栈、依赖项、配对记录和故障模式与 Apple TV 控制相互隔离。

pymobiledevice3 仅限于单独分发的 appletv-screenshot 辅助程序使用。主 appletv-mcp 软件包不会导入或捆绑它；两个进程通过精简的命令行／文件约定进行通信。

---

专为 Agent 设计

MCP 接口有意提供语义操作，而不是原始 Apple 协议。

Agent 应该这样理解：

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

而不是：

send Companion command
call MRP endpoint
construct RemoteXPC request

有语义操作时，应优先使用它。

对于需要视觉操作的界面，视觉导航是备用方案。

---

隐私与安全

Apple TV MCP 的设计目标是始终在本地运行。

• 没有托管的 Apple TV MCP 后端
• 无云账户
• MCP 使用本地 stdio 传输
• Apple TV 配对凭据保留在用户的设备上
• RemoteXPC 配对记录保留在截图辅助程序中
• 凭据不会作为 MCP 参数传递
• 凭据不会返回给模型
• 键盘输入文本不会写入常规日志
• 仅在明确请求时才会截取屏幕截图
• 不会记录截图字节
• 截图期间仅将截图存储在私有临时目录中
• 创建 MCP 结果后会删除临时截图文件
• 命令执行后不会自动截取屏幕截图
• 启动辅助程序时不会使用 shell
• 不会尝试规避 DRM

调试模式也会继续禁用原始 pyatv 协议日志记录，因为低级 Companion 流量可能包含敏感的键盘输入和配对负载。

---

受保护的视频

流媒体应用可能会使用 DRM 保护视频。

这种情况下，截图中可能会出现：

black video
blank video
redacted video

同时仍能看到菜单或播放控件。

这是预期行为。

Apple TV MCP 不会将受保护视频区域为黑色解读为以下情况的证据：

• 播放失败
• Apple TV 已关闭
• 截图失败

也不会尝试绕过 DRM。

---

限制

Apple TV MCP 刻意将初始范围限定得较窄。

一台 Apple TV

每个服务器配置控制一台 Apple TV。

目前，公开的 MCP 接口不支持多设备路由。

截图不是视频

apple_tv_screenshot 每次截取一帧。

它不支持：

• 连续视频流
• 后台屏幕监控
• 屏幕录制
• 自动循环截图

焦点依靠视觉判断，而非语义信号

pyatv 不提供通用信号来指示当前高亮的 tvOS 元素。

Agent 可在适当情况下使用截图推断焦点。

media_app 不等于 foreground_app

Apple TV 状态可能会指出与当前媒体元数据相关联的应用。

但这并不能独立保证哪个应用在视觉上位于前台。

Apple 开发者服务可能会变更

截图功能依赖于通过 pymobiledevice3 提供的 Apple 开发者协议。

tvOS 的变更可能需要后续进行兼容性更新。

截图支持为可选功能

即使未安装截图辅助程序，所有非截图类 Apple TV MCP 工具仍可使用。

---

配置

Apple TV MCP 会将应用配置存储在平台标准的配置目录中。

典型设置包括：

{
  "device_identifier": "...",
  "device_name": "Living Room",
  "preferred_host": "192.168.1.10",
  "scan_timeout_seconds": 5.0,
  "command_timeout_seconds": 15.0,
  "screen_capture": {
    "command": "appletv-screenshot",
    "timeout_seconds": 20.0,
    "max_image_bytes": 33554432
  }
}

配对凭据不会存储在此文件中。

如果 MCP 主机使用精简的 PATH 启动进程，请将 screen_capture.command 设置为截图辅助程序的绝对路径。

Apple TV MCP v0.1 的现有配置文件仍然兼容。

---

Doctor

运行：

appletv-mcp doctor

以诊断完整安装情况。

它会检查以下方面：

configuration
pyatv storage
Apple TV discovery
stable device identity
connection
capabilities
screenshot helper
screenshot helper contract
screen-capture target
real screenshot capture

截图支持是可选的。

如果未安装辅助工具，Doctor 会将其报告为已跳过，而不会因此判定 Apple TV 控制功能异常。

---

故障排查

找不到 Apple TV

确认：

• Apple TV 已开机
• 电脑和 Apple TV 位于同一本地网络
• atvremote wizard 已成功完成

然后重新运行：

appletv-mcp configure
appletv-mcp doctor

Apple TV IP 地址已更改

这是正常情况。

Apple TV MCP 会通过稳定标识符识别已配置的设备，而不会依赖旧 IP 地址。

应用无法打开

使用：

apple_tv_list_apps

查看设备当前提供的应用。

应用名称匹配采用确定性方式，而非模糊匹配。

文本输入失败

Apple TV 上必须已有获得焦点的文本字段。

找不到截图辅助工具

安装它：

uv tool install appletv-screenshot

或为 Apple TV MCP 配置其绝对路径。

未配置截图目标

运行：

appletv-screenshot configure --udid <UDID>

截图配对失败

开发者截图配对与 atvremote 相互独立。

运行：

pymobiledevice3 remote pair

截图为黑屏

受保护的内容可能会有意隐藏视频画面。

尝试打开 tvOS 菜单或应用界面，然后重新截图。

---

开发

克隆仓库：

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

安装：

uv sync --locked

运行完整的根目录质量检查：

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build

截图辅助工具是一个独立的 Python 项目：

cd sidecars/appletv-screenshot
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

根软件包有意不依赖或捆绑 pymobiledevice3。

---

实时测试

常规测试使用模拟对象，无需 Apple 硬件。

只读 Apple TV 集成测试需要明确选择启用：

APPLE_TV_INTEGRATION_TESTS=1 uv run pytest -m live

可能会更改 Apple TV 状态的测试还需要额外选择启用：

APPLE_TV_INTEGRATION_TESTS=1 \
APPLE_TV_LIVE_WRITES=1 \
uv run pytest -m live

切勿对你不打算控制的设备启用实时写入测试套件。

---

贡献

欢迎贡献。

提交拉取请求前：

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build

如果你的更改影响截图辅助工具，也请运行其独立的质量检查。

请保留项目的核心架构：

control      = pyatv
observation  = external screenshot helper
MCP          = semantic interface presented to the agent

除非有明确的语义理由，否则避免通过 MCP 契约暴露原始 Apple 协议细节。

---

许可证

本仓库包含两个分别分发的组件。

Apple TV MCP

appletv-mcp 根据 MIT 许可证授权。

它不会导入、捆绑或分发 pymobiledevice3。

Apple TV Screenshot

位于 sidecars/appletv-screenshot/ 下的可选辅助工具 appletv-screenshot 根据 GPL-3.0-or-later 许可证授权。

该辅助工具直接使用 pymobiledevice3，后者也根据 GPL-3.0-or-later 许可证授权。

这两个组件通过一次性子进程接口进行通信。

请参阅 LICENSING.md 了解整个仓库的许可证概览。

---

为一个简单的理念而构建

AI Agent 能够验证其操作的效果时，会实用得多。

Apple TV MCP 为它们提供了这个闭环的两端：

control the Apple TV
        +
see the Apple TV

因此，Agent 无需盲目按按钮，而是可以与 tvOS 交互、检查结果，并决定下一步操作。