AI导哈

Sonos控制服务器

SoniqMCP是一个MCP服务器，允许通过兼容MCP的AI客户端控制Sonos系统，支持本地运行或通过Docker、Helm/k3s部署。

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

使用说明

SoniqMCP--Sonos MCP服务器

从任何兼容MCP的AI客户端控制Sonos系统。通过stdio在本地运行，在Linux上部署Docker以实现全家庭访问，或者在其网络警告适合您的环境时遵循有记录的Helm/k3s指南。

它做什么

SoniqMCP是一个 主控程序 服务器，将Sonos系统作为AI代理的工具公开。连接Claude Desktop（或任何MCP客户端），通过自然对话控制播放、音量、队列、收藏夹、播放列表、本地音乐库浏览和播放以及房间分组。

可用工具：

类别 工具
系统 list_rooms, get_system_topology
播放 play, pause, stop, next_track, previous_track, get_playback_state, get_track_info
播放模式 get_play_mode, set_play_mode, seek, get_sleep_timer, set_sleep_timer
音量 get_volume, set_volume, adjust_volume, mute, unmute, get_mute
房间音响 get_eq_settings, set_bass, set_treble, set_loudness
排队 get_queue, add_to_queue, remove_from_queue, clear_queue, play_from_queue
收藏夹 list_favourites, play_favourite
报警生命周期 list_alarms, create_alarm, update_alarm, delete_alarm
播放列表播放和生命周期 list_playlists, play_playlist, create_playlist, update_playlist, delete_playlist
当地音乐图书馆 browse_library, play_library_item
团体 get_group_topology, join_group, unjoin_room, party_mode, group_rooms
组音频 get_group_volume, set_group_volume, adjust_group_volume, group_mute, group_unmute
输入 switch_to_line_in, switch_to_tv
安装程序 ping, server_info

快速启动

先决条件： Python 3.12+， 紫外线

# 1. Clone and install
git clone <repo-url> sonos-mcp-server
cd sonos-mcp-server
make install        # runs: uv sync

# 2. Configure (copy and edit)
cp .env.example .env

# 3. Run
make run            # starts the server over stdio

看 docs/setup/stdio.md 有关完整的本地设置指南，包括Claude Desktop接线。服务器运行后，使用 docs/promises/example-uses.md 用于直接和代理介导的提示示例和使用 docs/promises/command-reference.md 作为规范命令界面。

部署模型

本地stdio Docker（HTTP） Helm/k3s（HTTP）
最适合 同机AI客户端 Linux家庭实验室服务器 自托管k3s/Kubernetes
客户端位置 仅限同一台机器 任何网络客户端 任何网络客户机

看 docs/setup/README.md 查看完整的部署比较和设置指南。

配置

所有配置都是通过项目本地进行的 .env 文件或环境变量。 当两者都存在时，环境变量获胜：

变量 默认值 描述
SONIQ_MCP_TRANSPORT stdio 运输方式(stdio 或 http)
SONIQ_MCP_EXPOSURE local 网络曝光态势(local 或 home-network)
SONIQ_MCP_LOG_LEVEL INFO 日志级别（调试/信息/警告/错误）
SONIQ_MCP_DEFAULT_ROOM （无） 可选默认Sonos房间
SONIQ_MCP_MAX_VOLUME_PCT 80 容量安全帽（0–100）
SONIQ_MCP_TOOLS_DISABLED （无） 逗号分隔的禁用工具
SONIQ_MCP_HTTP_HOST 127.0.0.1 绑定地址（仅限HTTP传输；对于家庭网络访问，也设置 SONIQ_MCP_EXPOSURE=home-network 并使用 0.0.0.0 或LAN地址）
SONIQ_MCP_HTTP_PORT 8000 端口（仅限HTTP传输）
SONIQ_MCP_AUTH_MODE none HTTP身份验证模式： none, static，或 oidc （仅限HTTP传输）

有关静态和OIDC身份验证配置，请参阅 docs/setup/authentication.md.

命令表面

受支持的指挥界面位于 docs/promises/command-reference.md。该页面是以下内容的规范参考：

  • make 开发目标、质量门、Docker、Compose和Helm
  • 直接CLI调用示例
  • 地方之间的关系 stdio 工作流和远程 Streamable HTTP 部署路径

文档

相关 MCP