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-pyatvClaude桌面配置
将此添加到您的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客户。服务器处理其余部分：
- 它扫描您的网络并发现设备。
- 您的电视屏幕上会显示一个PIN。
- 你告诉客户PIN。
- 凭据存储在本地，并在会话之间持久。
每个设备只需配对一次。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中的异步兼容性问题，目前不支持
建立在
有关协议详细信息、与设备通信相关的错误报告，或为底层库做出贡献，请访问：
许可证
麻省理工学院——见 许可证 了解详情。