appletv-mcp

一个 MCP 服务器，让 AI 代理能够通过本地网络完全控制 Apple TV——无需遥控器，无需 Siri。

基于 pyatv（Companion + AirPlay 协议）构建。姊妹项目 appletv-remote 以 Claude Code / opencode 技能的形式提供相同功能，而非服务器。

功能一览

控制工具接受可选的 device 名称以指定非默认电视（atv_scan、atv_devices 和 atv_use 除外——它们作用于配对配置本身）。

安装

前置条件： uv（brew install uv）。

1. 每台电视配对一次（交互式；电视会两次显示 4 位 PIN 码）：

uv run python scripts/pair.py

凭据以仅所有者可读的权限存储在 ~/.config/appletv-remote/devices.json 中（与 appletv-remote 技能共享）。请妥善保管该文件——它拥有对电视的完全控制权。

非交互式（代理驱动）：设置 ATV_PIN_FILE=/tmp/atv_pin.txt，运行 pair.py <name-filter>，并将每个 PIN 码写入该文件。

2. 向 MCP 客户端注册服务器。以 opencode 为例（~/.config/opencode/opencode.json）：

"mcp": {
  "appletv": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/path/to/appletv-mcp", "python", "server.py"],
    "enabled": true
  }
}

对于 Claude Code：claude mcp add appletv -- uv run --directory /path/to/appletv-mcp python server.py

注意事项与已知问题

• pyatv 被固定在一个未合并分支的精确提交上，用于修复 tvOS 26 上的 play_url 问题（PR #2846，issue #2821/#2774）。合并并发布后，请切换回官方 pyatv。

• Netflix 深度链接不可靠，因其 2025 年 9 月的 tvOS 应用更新；atv_watch 会优雅降级，你也可以随时使用 atv_launch_app("netflix") + atv_type(...)。

• JustWatch 查询默认使用美国/英语；可通过 ATV_JW_COUNTRY / ATV_JW_LANGUAGE 覆盖。

• YouTube 流通过 AirPlay 2 以 HLS 方式推送：播放会在电视上排队，工具返回后继续播放。URL 约 6 小时后过期。

• 连接时出现 FetchAttentionState failed 警告属正常现象（分支特性）；命令仍可正常工作。

• 已在 tvOS 26（Apple TV 4K 第 3 代）上测试。tvOS 13+ 应可正常工作。

许可证

MIT