使用说明

Sonos TypeScript MCP服务器

您的全面Sonos控制伴侣由模型上下文协议（MCP）提供支持。此智能服务器使用UPnP/SOAP协议通过您的本地网络提供对Sonos音频设备的无缝访问。无论您是控制播放、管理区域、浏览音乐库还是设置闹钟，此MCP服务器都可以直接向您的AI助手提供完整的设备控制，实现智能家居自动化和更好的音频体验。

专为编码代理和AI驱动的家庭音频自动化工作流程而设计。 该服务器使AI助手能够构建智能多房间音频体验、音乐库管理、区域分组、队列管理以及与智能家居平台的集成。

数据来源于与Sonos设备的实时UPnP/SOAP通信，以确保准确性和完整性。

📊 功能状态：第四阶段完成！使用UPnP GENA协议实现实时事件订阅，用于播放、卷、队列和拓扑更改。看第四阶段完成了解详情。

📚 文档

综合工具说明 -为编码代理提供详细指南，包括所有50多种工具的用例、工作流程和最佳实践
api参考 -API技术文件
示例脚本 -自动化脚本和用例示例

入门指南

Sonos TypeScript MCP服务器可以与任何支持标准I/O（stdio）作为传输介质的MCP客户端一起工作。以下是一些流行工具的具体说明：

基本配置

克劳德桌面版

要配置Claude Desktop以使用Sonos MCP服务器，请编辑 claude_desktop_config.json 文件。您可以从Claude>Settings菜单打开或创建此文件。选择“开发人员”选项卡，然后单击“编辑配置”。

{
  "mcpServers": {
    "sonos-ts-mcp": {
      "command": "npx",
      "args": ["-y", "sonos-ts-mcp@latest"]
    }
  }
}

克莱恩

要配置Cline以使用Sonos MCP服务器，请编辑 cline_mcp_settings.json 文件。您可以通过单击Cline窗格顶部的MCP服务器图标，然后单击配置MCP服务器按钮来打开或创建此文件。

{
  "mcpServers": {
    "sonos-ts-mcp": {
      "command": "npx",
      "args": ["-y", "sonos-ts-mcp@latest"],
      "disabled": false
    }
  }
}

光标

要配置Cursor以使用Sonos MCP服务器，请编辑以下文件之一 .cursor/mcp.json （仅配置特定项目）或文件 ~/.cursor/mcp.json （使MCP服务器在所有项目中可用）：

{
  "mcpServers": {
    "sonos-ts-mcp": {
      "command": "npx",
      "args": ["-y", "sonos-ts-mcp@latest"]
    }
  }
}

Visual Studio代码副本

要配置单个项目，请编辑 .vscode/mcp.json 工作区中的文件：

{
  "servers": {
    "sonos-ts-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sonos-ts-mcp@latest"]
    }
  }
}

要使服务器在您打开的每个项目中都可用，请编辑您的用户设置：

{
  "mcp": {
    "servers": {
      "sonos-ts-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "sonos-ts-mcp@latest"]
      }
    }
  }
}

Windsurf编辑器

要配置Windsurf编辑器，请编辑文件 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sonos-ts-mcp": {
      "command": "npx",
      "args": ["-y", "sonos-ts-mcp@latest"]
    }
  }
}

使用代理进行测试

您可以使用内置的CLI代理快速测试MCP服务器，该代理使用自然语言与Sonos系统交互：

# Run directly with npx (no installation required)
npx sonos-agent-cli "Play jazz in the living room"

# Use a specific AI model
npx sonos-agent-cli "What's playing in the kitchen?" --model gpt-4o

# Use Gemini models
npx sonos-agent-cli "Set volume to 50 in all rooms" --model gemini-3-pro-preview

所需的环境变量：

OPENAI_API_KEY：适用于OpenAI模型（gpt-4o、gpt-4o-mini等）
GOOGLE_GENERATIVE_AI_API_KEY：适用于Gemini型号
SONOS_AGENT_MODEL：设置默认模型（可选）

构建行为：

CLI在运行之前会自动构建MCP服务器，以确保使用最新代码。要跳过构建（例如，在快速测试期间），请使用 --skip-build:

npx sonos-agent-cli "Play music" --skip-build

此代理提供了一种简单的方法来验证MCP服务器是否正常工作，并且可以与您的Sonos设备通信。

特性

此MCP服务器提供对Sonos音响系统的全面控制：

AI驱动的代理工具：通过自然语言控制 sonos_agent 工具（需要AI API密钥）✨ 新
拓扑持久性：设备拓扑自动保存到磁盘并在启动时加载
智能设备分辨率：按友好名称（例如“厨房”）而不是UUID控制设备
自动发现：启动时和每5分钟发现一次设备
设备发现：基于SSDP的Sonos设备手动发现
回放控制：播放、暂停、停止、下一个、上一个
音量控制：获取和设置音量级别，静音/取消静音
交通信息：获取当前播放状态和曲目信息
区域拓扑：查询区域组和扬声器配置
队列管理：完全队列控制（添加、删除、重新排序、保存、播放）
DIDL精简版支持：完成曲目、专辑和容器的元数据处理
播放属性：洗牌、重复和交叉火力控制
组管理：加入和取消加入设备以创建多房间组
音乐库浏览：浏览艺术家、专辑、曲目、流派和播放列表
库搜索：在音乐库中进行模糊搜索
音频/均衡器控制：低音、高音、响度、夜间模式、对话增强
睡眠定时器：持续时间后自动停止播放
报警管理：创建、更新和删除警报
快照/还原：保存并恢复完整的设备状态
聚会模式：一次加入所有设备
事件订阅：状态更改的实时通知✨ 新
MCP提示：将AI代理指令作为可发现的提示公开✨ 新
纯TypeScript：无需外部Sonos库即可从头开始构建
MCP兼容：与任何兼容MCP的客户端集成

计划功能（第5+阶段）

该项目正在积极扩展，以匹配Python SoCo库的全面功能集：

音乐服务集成（Spotify、Apple Music）
🟢 高级组管理（立体声对、家庭影院）
🟢 音频分析和诊断
🟢 MCP事件工具集成

请参阅第四阶段完成了解最新功能。

可用工具

AI代理工具✨ 新

工具	说明
`sonos_agent`	人工智能驱动的自然语言控制。给出“在客厅里演奏爵士乐”这样的指令，代理就会自主处理设备发现、工具选择和执行。仅在以下情况下可用 `OPENAI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY` 已配置。看代理工具文档了解详情。

发现工具

工具	说明
`sonos_discover`	使用SSDP多播在网络上发现Sonos设备
`sonos_add_device`	按IP地址手动添加Sonos设备（在SSDP发现失败时有用）
`sonos_list_devices`	列出所有发现/注册的设备

播放控制工具

工具	说明
`sonos_play`	开始播放
`sonos_pause`	暂停播放
`sonos_stop`	停止播放
`sonos_next`	跳到下一首曲目
`sonos_previous`	跳至上一曲目

音量控制工具

工具	说明
`sonos_set_volume`	设置音量（0-100）
`sonos_get_volume`	获取当前音量
`sonos_set_mute`	静音或取消静音

队列管理工具

工具	说明
`sonos_get_queue`	获取当前播放队列
`sonos_add_to_queue`	向队列添加URI
`sonos_remove_from_queue`	从队列中删除曲目
`sonos_clear_queue`	从队列中删除所有曲目
`sonos_play_from_queue`	从特定队列位置播放
`sonos_save_queue`	将队列另存为Sonos播放列表

播放属性工具

工具	说明
`sonos_set_shuffle`	启用或禁用随机播放模式
`sonos_set_repeat`	设置重复模式（关闭、全部、一）
`sonos_set_crossfade`	启用或禁用交叉火力
`sonos_get_playback_state`	获取混洗、重复、交叉拍摄和播放状态

组管理工具

工具	说明
`sonos_join_group`	将设备加入另一个设备的组
`sonos_unjoin`	从组中删除设备
`sonos_party_mode`	一次加入所有设备

音乐库工具

工具	说明
`sonos_browse_artists`	浏览音乐库中的所有艺术家
`sonos_browse_albums`	浏览音乐库中的所有相册
`sonos_browse_tracks`	浏览音乐库中的所有曲目
`sonos_browse_genres`	浏览音乐库中的所有流派
`sonos_browse_playlists`	浏览Sonos播放列表
`sonos_get_favorite_radio_stations`	从Sonos收藏夹中获取喜爱的广播电台
`sonos_search_library`	搜索音乐库
`sonos_browse_item`	浏览子类别（例如，艺术家的相册）

音乐服务工具

工具	说明
`sonos_list_music_services`	列出可用的音乐服务（Sonos Radio、TuneIn、Spotify等）
`sonos_browse_music_service`	浏览音乐服务中的内容（类别、电台、播放列表）
`sonos_search_music_service`	在音乐服务中搜索内容
`sonos_play_music_service_item`	播放音乐服务（广播电台、曲目、专辑）中的项目
`sonos_get_music_service_item_uri`	获取音乐服务项目的流媒体URI

音频/均衡器控制工具

工具	说明
`sonos_set_bass`	设置低音级别（-10到10）
`sonos_set_treble`	设置高音音量（-10到10）
`sonos_set_loudness`	启用/禁用响度补偿
`sonos_get_eq`	获取所有EQ设置
`sonos_set_night_mode`	启用/禁用夜间模式（家庭影院）
`sonos_set_dialog_mode`	启用/禁用对话增强功能（家庭影院）

睡眠定时器工具

工具	说明
`sonos_set_sleep_timer`	设置自动播放停止定时器
`sonos_get_sleep_timer`	获取剩余计时器
`sonos_cancel_sleep_timer`	取消睡眠定时器

报警管理工具

工具	说明
`sonos_list_alarms`	列出所有警报
`sonos_create_alarm`	创建新警报
`sonos_update_alarm`	更新现有警报
`sonos_delete_alarm`	删除警报

状态管理工具

工具	说明
`sonos_snapshot`	拍摄设备状态快照
`sonos_restore_snapshot`	从快照还原

活动订阅工具

工具	说明
`sonos_subscribe_events`	订阅实时设备事件（AVTransport、渲染控制、队列、ZoneGroupTopology、闹钟）
`sonos_unsubscribe_events`	取消订阅特定订阅
`sonos_unsubscribe_all`	取消订阅所有设备订阅
`sonos_list_subscriptions`	列出活动事件订阅

信息工具

工具	说明
`sonos_get_transport_info`	获取播放状态
`sonos_get_position_info`	获取当前曲目详细信息
`sonos_get_zone_groups`	获取区域拓扑

开发和安装

npm install
npm run build

测试发现

安装后，您可以测试是否可以发现Sonos设备：

npm run test:discovery

这将执行SSDP多播搜索，并显示在您的网络上找到的任何Sonos设备。

测试喜爱的电台

您可以测试喜爱的广播电台功能：

npm run test:radio

这将查询您的Sonos设备以查找已保存的电台并显示它们。如果没有找到电台，它将提供如何使用Sonos应用程序添加一些电台的说明。

测试代理工具

您可以测试AI驱动的代理工具（需要AI API密钥）：

# Set up your API key first
export OPENAI_API_KEY=sk-...
# or
export GOOGLE_GENERATIVE_AI_API_KEY=...

# Run the test
npm run test:agent-tool

这将验证代理工具是否配置正确，是否可以执行自然语言指令。请参阅代理工具文档了解更多详情。

用法

作为MCP服务器

服务器支持两种传输模式：

标准模式（默认）

标准模式是运行MCP服务器的标准方式，通过标准输入/输出进行通信。这是大多数MCP客户端使用的模式。

添加到MCP客户端配置中：

{
  "mcpServers": {
    "sonos": {
      "command": "node",
      "args": ["path/to/sonos-ts-mcp/dist/index.js"]
    }
  }
}

或者直接运行：

node dist/index.js

您还可以使用便利脚本：

npm run start:stdio
# or
tsx scripts/start-mcp-stdio.ts

CLI代理

该项目包括一个由Mastra支持的CLI代理，允许您使用自然语言控制Sonos系统。

# Run with default model (gpt-4o-mini)
npx sonos-agent-cli "Play jazz in the living room"

# Run with a specific model
npx sonos-agent-cli "Play jazz in the living room" --model gpt-4o

# Run with Gemini 3
npx sonos-agent-cli "Play jazz in the living room" --model gemini-3-pro-preview

环境变量：

OPENAI_API_KEY：OpenAI模型需要（默认）
GOOGLE_GENERATIVE_AI_API_KEY：Gemini型号需要
SONOS_AGENT_MODEL：设置默认模型（可选。， gemini-3-pro-preview)

遥测注意事项：在此实现中，Mastra框架的内置遥测功能已被禁用。通过设置抑制遥测警告 globalThis.___MASTRA_TELEMETRY___ = true 在Mastra初始化之前。这是在CLI代理中自动设置的。

SSE模式（HTTP服务器）

SSE（服务器发送事件）模式将MCP服务器作为HTTP服务器运行，这对于基于web的客户端或远程访问非常有用。

设置 MCP_TRANSPORT 环境变量 sse:

MCP_TRANSPORT=sse node dist/index.js

或者使用自定义端口（默认值为3000）：

MCP_TRANSPORT=sse MCP_PORT=8080 node dist/index.js

您还可以使用便利脚本：

npm run start:sse
# or
tsx scripts/start-mcp-sse.ts

使用自定义端口：

MCP_PORT=8080 npm run start:sse

服务器将在以下位置启动HTTP端点 http://localhost:3000/sse 客户端可以连接到的端口（或您配置的端口）。

发展

npm run dev            # Run with tsx (hot reload)
npm run build          # Compile TypeScript
npm run typecheck      # Type checking only
npm run lint           # ESLint
npm run format         # Prettier
npm test               # Run tests
npm run test:discovery # Test Sonos device discovery
npm run test:phase1    # Test Phase 1 APIs (Queue, Playback)
npm run test:phase2    # Test Phase 2 APIs (Groups, Library)
npm run test:phase3    # Test Phase 3 APIs (Audio, Alarms)
npm run test:phase4    # Test Phase 4 APIs (Events)
npm run test:all-phases # Run all phase tests

测试

全面的API测试脚本可用于所有实现的功能：

# Run all tests
npm run test:all-phases

# Or run individual phase tests
npm run test:phase1  # Queue, DIDL, Playback Properties
npm run test:phase2  # Groups & Music Library Browsing
npm run test:phase3  # Audio, Alarms, Snapshots
npm run test:phase4  # Event Subscriptions

# Run Phase 2 tests in mock mode (no physical devices required)
npm run test:phase2 -- --mock

# Run integration tests (uses AI validation)
npm test

备注：第2阶段测试支持模拟模式，用于在没有物理Sonos设备的情况下进行测试。使用 --mock 标志或集合 MOCK_DEVICES=true 环境变量。

AI驱动的集成测试：集成测试套件使用Gemini 2.5 Flash AI智能验证代理输出，而不是脆弱的字符串匹配。这提供了对测试结果的语义理解，并适应不同的输出格式。需要 GOOGLE_GENERATIVE_AI_API_KEY 环境变量。

请参阅 API测试指南和 AI驱动测试指南有关测试套件的详细文档。

建筑

src/
├── discovery/         # SSDP device discovery
│   ├── ssdp-client.ts
│   └── device-registry.ts
├── didl/             # DIDL-Lite metadata handling
│   ├── didl-object.ts
│   ├── didl-resource.ts
│   ├── didl-item.ts
│   ├── didl-container.ts
│   ├── didl-serializer.ts
│   ├── didl-parser.ts
│   └── index.ts
├── soap/             # SOAP/UPnP transport layer
│   ├── client.ts
│   ├── request-builder.ts
│   └── response-parser.ts
├── services/         # Sonos service wrappers
│   ├── base-service.ts
│   ├── av-transport.ts        # Playback, queue, sleep timer
│   ├── rendering-control.ts   # Volume, EQ, audio enhancements
│   ├── zone-topology.ts       # Groups, party mode
│   ├── content-directory.ts   # Music library browsing
│   ├── alarm-clock.ts         # ✨ NEW: Alarm management
│   └── snapshot.ts            # ✨ NEW: State snapshot/restore
├── mcp/             # MCP server implementation
│   └── server.ts
└── types/           # TypeScript definitions
    ├── sonos.ts
    └── queue.ts

协议细节

发现（SSDP）

向发送UDP多播 239.255.255.250:1900
搜索 urn:schemas-upnp-org:device:ZonePlayer:1
解析响应标头以提取设备位置

关于发现的说明：SSDP多播发现可能无法在所有网络环境中工作，原因如下：

Windows防火墙阻止UDP端口1900
网络交换机未正确转发多播流量
VPN对组播路由的干扰
企业网络政策

如果自动发现失败，请使用 sonos_add_device 通过IP地址手动注册设备的工具。服务器将在注册设备之前验证连接。

手动设备注册

当SSDP发现不起作用时，您可以手动添加设备：

// Using the MCP tool
sonos_add_device({
  ip: "192.168.1.100",
  port: 1400,  // optional, defaults to 1400
  name: "Kitchen"  // optional, defaults to "Sonos at {ip}"
})

服务器将在将设备添加到注册表之前测试其连接。

控制（SOAP/UPnP）

HTTP POST到 http://{ip}:1400/...
基于XML的SOAP信封
支持所有标准Sonos UPnP服务

文档

🤖 代理工具指南 -人工智能驱动的自然语言控制✨ 新
📚 综合工具说明 -为编码代理提供详细指南，包括所有50多种工具的用例、工作流程和最佳实践
📦 安装指南 -详细的安装和配置说明
💾 拓扑持久性指南 -设备拓扑存储和管理✨ 新
🎯 设备分辨率指南 -使用友好的设备名称✨ 新
🧪 API测试指南 -全面的测试套件文档
📘 实施指南 -工具使用和示例
🏗️ 技术架构 -系统设计细节
📚 阶段完成文件 -第1阶段已完成.md至第4阶段已完成-md

贡献

欢迎投稿！该项目正在扩展，以提供全面的Sonos控制。请参阅路线图对于计划中的功能。

贡献特别有价值的领域：

实施其他UPnP服务
添加DIDL Lite对象模型
活动订阅系统
测试覆盖范围扩展
文档改进

许可证

麻省理工学院