Sonos MCP Server

Sonos MCP 服务

此项目是一个 Sonos MCP（Model Context Protocol）服务，可让你控制和使用网络中的 Sonos 设备。它提供多种功能，例如发现设备、控制播放、获取设备状态以及管理队列。

功能

• 发现网络中的 Sonos 设备
• 获取和控制设备的播放状态
• 管理播放队列
• 将功能作为 MCP 工具公开

要求

• Python 3.12+
• 用于管理 Python 项目的 uv

安装

从 Git 直接安装

pip install git+https://github.com/WinstonFassett/sonos-mcp-server.git

开发环境

1. 克隆仓库：

   git clone https://github.com/WinstonFassett/sonos-mcp-server.git
   cd sonos-mcp-server
   

2. 使用 uv 安装所需依赖：

   uv sync
   

用法

运行服务

Stdio

使用 stdio 运行服务：

uv run mcp run server.py

HTTP（streamable-http）

服务原生支持 MCP streamable-http 传输方式（mcp SDK >= 1.12），无需代理：

SONOS_MCP_TRANSPORT=streamable-http \
SONOS_MCP_HOST=127.0.0.1 \
SONOS_MCP_PORT=8090 \
uv run sonos-mcp-server

端点：http://127.0.0.1:8090/mcp

环境变量：

变量	默认值	说明
SONOS_MCP_TRANSPORT	stdio	stdio、sse 或 streamable-http
SONOS_MCP_HOST	127.0.0.1	HTTP 绑定地址
SONOS_MCP_PORT	8000	HTTP 端口（路径为 /mcp）
SONOS_MCP_ALLOWED_HOSTS	(仅限 localhost)	要接受的额外 Host 标头，以逗号分隔。通过不同主机名的代理提供服务时需要设置（例如 mac-mini.tailc3138.ts.net:*）。
SONOS_DEVICE_IPS	(SSDP 发现)	以逗号分隔的扬声器 IP 地址。跳过 SSDP 多播，并通过单播 SOAP 解析名称；当进程无法进行多播时需要设置（例如未获得本地网络权限的 launchd）。

旧版：使用 supergateway 的 SSE

较旧的替代方案（已弃用，建议使用上文的 streamable-http）：

npx -y supergateway --port 8000 --stdio "uv run mcp run server.py"

开发

若要在“开发”模式下使用 MCP Inspector 运行服务：

uv run mcp dev server.py

此命令会启动 MCP Inspector，用于测试和调试。

若要在开发模式下使用 SSE 运行服务，请使用 supergateway 的 SSE 命令，并在第二个终端窗口中运行：

npx @modelcontextprotocol/inspector

安装到 Claude Desktop

发布到 Git 后，用户可以直接安装：

mcp install git+https://github.com/WinstonFassett/sonos-mcp-server.git

或者添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "sonos": {
      "command": "sonos-mcp-server"
    }
  }
}

可用的 MCP 工具

使用公开的 MCP 工具与 Sonos 设备交互。可用工具包括：

• get_all_device_states：获取所有已发现 Sonos 设备的状态信息。
• now_playing：获取所有 Sonos 设备当前播放曲目的信息。
• get_device_state：获取指定 Sonos 设备的状态信息。
• pause、stop、play：控制 Sonos 设备的播放。
• next、previous：跳过 Sonos 设备上的曲目。
• get_queue、get_queue_length：管理 Sonos 设备的播放队列。
• mode：获取或设置 Sonos 设备的播放模式。
• partymode：在当前 Sonos 设备上启用派对模式。
• speaker_info：获取 Sonos 设备的扬声器信息。
• get_current_track_info：获取 Sonos 设备当前曲目的信息。
• volume：获取或设置 Sonos 设备的音量。
• skip、play_index、remove_index_from_queue：管理 Sonos 设备队列中的曲目。
• add_service_tracks_to_queue：将 Spotify、Apple Music、Tidal 或 Deezer 等音乐服务中的曲目添加到 Sonos 队列。

发布更新

进行更改后：

git add .
git commit -m "Description of changes"
git push

用户可以通过以下方式更新：

pip install --upgrade git+https://github.com/WinstonFassett/sonos-mcp-server.git

许可证

此项目采用 MIT License 授权。详情请参阅 LICENSE 文件。