MCP Pyatv

mcp-pyatv

MCP服务器，用于通过以下方式控制Apple TV、HomePod和AirPlay设备 pyatv.

______________________________________________________________________

它的作用

这使您可以通过Claude Desktop、Claude Code、Cursor或任何其他兼容MCP的客户端使用自然语言控制您的设备。

此项目不实现任何设备协议。 所有协议级通信均由pyatv处理。mcp-pyatv纯粹是mcp桥接层。

支持设备

• 苹果电视 --所有世代，包括tvOS 15+
• HomePod/迷你HomePod
• AirPort 快线
• 第三方AirPlay扬声器
• macOS （音乐/iTunes）

快速开始

安装

pip install mcp-pyatv

或者直接运行而不安装：

uvx mcp-pyatv

Claude桌面配置

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

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

注： Claude Desktop可能不会继承shell的PATH。如果收到“找不到命令”错误，请使用完整路径 uvx （奔跑 which uvx 在您的终端中找到它）： ``json { "mcpServers": { "apple-tv": { "command": "/Users/you/.local/bin/uvx", "args": ["--python", "python3.13", "mcp-pyatv"] } } } ``

本地开发

如果你已经克隆了仓库，并想从源代码运行：

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

首次使用/配对

第一次使用时，只需说 “配对我的Apple TV” 您的MCP客户。服务器处理其余部分：

1. 它扫描您的网络并发现设备。
2. 您的电视屏幕上会显示一个PIN。
3. 你告诉客户PIN。
4. 凭据存储在本地，并在会话之间持久。

每个设备只需配对一次。HomePod不需要配对。

可用工具

mcp-pyatv公开了32个按类别组织的工具：

发现

配对

回放

导航

音频

应用

力量

键盘

流媒体

媒体信息

对话示例

检查正在播放的内容：

“我的Apple TV上正在播放什么？” 服务器调用 scan_devices 找到你的Apple TV，然后 now_playing 以获取当前曲目/节目信息。

启动应用程序：

“打开Netflix” 服务器调用 launch_app 使用Netflix捆绑包ID。

调节音量：

“将音量设置为40” 服务器调用 set_volume 40级。

配对新设备：

“配对我的Apple TV” 服务器调用 scan_devices那么 start_pairing。您的电视上会出现一个PIN。您说“PIN是1234”，服务器就会呼叫 finish_pairing 以完成该过程。

配置

默认凭据文件(~/.pyatv.conf)与pyatv共享 atvremote CLI工具。如果您已经使用配对设备 atvremote，mcp-pyatv将自动获取这些凭据。

已知限制

• play_url 在tvOS 26.x上损坏 --上游pyatv问题(#2821)
• stop 被一些应用程序忽略 --YouTube和某些其他应用程序不响应停止命令
• get_artwork 取决于应用程序 --并非所有应用都公开艺术品元数据
• 需要相同的网络 --您的计算机必须与设备位于同一WiFi网络上
• set_shuffle / set_repeat --需要活动的音乐播放队列才能工作
• Python 3.14 --由于pyatv中的异步兼容性问题，目前不支持

建立在

有关协议详细信息、与设备通信相关的错误报告，或为底层库做出贡献，请访问：

• pyatv文档

许可证

麻省理工学院——见 许可证 了解详情。