Sonos Ts MCP

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代理工具✨ 新

发现工具

播放控制工具

音量控制工具

队列管理工具

播放属性工具

组管理工具

音乐库工具

音乐服务工具

音频/均衡器控制工具

睡眠定时器工具

报警管理工具

状态管理工具

活动订阅工具

信息工具

开发和安装

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对象模型
• 活动订阅系统
• 测试覆盖范围扩展
• 文档改进

许可证

麻省理工学院