AI导哈

Apple设备控制服务器

mcp-pyatv是一个通过pyatv控制Apple TV、HomePod和AirPlay设备的MCP服务器，可作为MCP客户端与本地网络上的Apple设备之间的桥梁。

  • by crlian
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 crlian/mcp-pyatv

使用说明

mcp-pyatv

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

它的作用

mcp pyatv是一个 MCP（模型上下文协议） 将任何MCP客户端连接到本地网络上的Apple TV、HomePod和AirPlay设备的服务器 pyatv --开源Python库，实现了实际的Apple TV和AirPlay协议，并将其功能作为MCP工具公开。

这使您可以通过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 在您的终端中找到它）：

{
  "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个按类别组织的工具：

发现

工具 说明
scan_devices 扫描本地网络以查找Apple TV和AirPlay设备
device_info 获取特定设备的详细信息

配对

工具 说明
start_pairing 使用设备开始配对过程
finish_pairing 通过提交屏幕上显示的PIN完成配对

回放

工具 说明
play 恢复播放
pause 暂停播放
play_pause 切换播放/暂停
stop 停止播放
next_track 跳到下一首曲目
previous_track 转到上一曲目
skip_forward 向前跳几秒钟
skip_backward 向后跳几秒钟
set_position 寻求一个特定的职位
set_shuffle 设置洗牌模式
set_repeat 设置重复模式

导航

工具 说明
navigate 发送远程控制命令——支持 up, down, left, right, select, menu, home, top_menu 和 single_tap, double_tap，或 hold 行动

音频

工具 说明
get_volume 获取当前音量水平
set_volume 将音量设置为特定级别
volume_up 增加音量
volume_down 减少音量

应用

工具 说明
list_apps 列出所有已安装的应用程序
launch_app 按名称或捆绑包ID启动应用程序

力量

工具 说明
turn_on 打开设备
turn_off 关闭/使设备进入睡眠状态
power_state 检查设备是否打开或关闭

键盘

工具 说明
set_text 在文本字段（例如搜索框）中键入文本
get_text 获取当前文本字段内容
clear_text 清除当前文本字段

流媒体

工具 说明
play_url 将媒体从URL流式传输到设备
stream_file 将本地文件流式传输到设备

媒体信息

工具 说明
now_playing 获取当前正在播放的内容的信息
get_artwork 获取当前播放媒体的艺术作品

对话示例

检查正在播放的内容：

“我的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 以完成该过程。

配置

变量 描述 默认值
MCP_PYATV_STORAGE_PATH 覆盖存储配对凭据的文件路径 ~/.pyatv.conf

默认凭据文件(~/.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 通过 皮埃尔 斯塔尔 --实现苹果设备使用的Companion、AirPlay、RAOP、MRP和DMAP协议的Python库。所有协议级通信、设备发现和配对逻辑都发生在pyatv内部。mcp-pyatv仅在顶部提供mcp服务器层。

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

许可证

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

相关 MCP