DEV Community

Cover image for I let Claude control my Sonos over MCP — here's what the Sonos APIs actually allow
Sam Seah
Sam Seah

Posted on

I let Claude control my Sonos over MCP — here's what the Sonos APIs actually allow

#api #claude #ios #mcp


I built ZoneFoundry for Sonos because of two daily annoyances: my music lives in four services (Apple Music, Spotify, QQ Music, NetEase) and the official app treats them as separate worlds; and Sonos voice control doesn't understand Cantonese or Mandarin. A year of nights and weekends later it's on the App Store (free, iOS 18+), and the part I use most is something I only built for debugging: an MCP server that lets Claude run my speakers.

This post is the technical part — what the Sonos APIs let you do, where they stop, and how the MCP layer fits.

Three ways to talk to a Sonos speaker

There are three control paths, and every feature in the app maps to one of them:

  1. LAN — UPnP/SOAP. Each speaker exposes services (AVTransport, RenderingControl, ContentDirectory…) over HTTP on the local network. No account, no cloud, sub-100 ms round trips. This is what the official app used for a decade.
  2. Cloud — the Sonos Control API. OAuth, HTTPS, works from anywhere. Playback, grouping, volume, favorites, playlists, audio clips (announcements). Rate-limited per household.
  3. SMAPI — the music-service interface. How Sonos itself browses and resolves tracks from Apple Music, Spotify, QQ Music, NetEase and the rest.

The design rule I ended up with: on the home Wi-Fi, use the LAN; away from home, use the cloud; never require a resident process at home unless the API genuinely leaves no other way. Then I went through the feature list one by one. The list is a Swift file where every entry is tagged free, partial or required (for a home-side bridge), so the number can't drift: 46 of 50 features need nothing installed at home.

The four that can't be done from the cloud

EQ, alarms, battery level and line-in/TV input. The cloud Control API simply doesn't expose them, so they are LAN-only. If you want to change EQ from the office, something at home has to be awake — I ship an optional tiny Docker bridge for that and say so in the app, rather than pretend it works.

The one I got wrong for months

Writing to Sonos Favorites was "impossible over LAN" in three comments in my own code, and I had built paywalls around that belief. It's wrong. CreateObject on the ContentDirectory service exists in the speaker's SCPD; what fails is hand-built DIDL-Lite metadata — the speaker rejects it with UPnP error 803. Take the exact TrackMetaData the speaker itself returns from GetPositionInfo, wrap it unchanged, and it works, for every music service I tried. Lesson: don't trust comments about hardware — send the SOAP call.

Voice in three languages, with an undo button

Recognition was the easy part (on-device iOS speech is excellent for Cantonese and Mandarin). The hard part is multi-intent sentences — "set the bedroom to 30 and the bathroom to 20" — and what happens when you got it wrong. Every action produces a receipt, and every receipt has an undo. That mattered more to my family than accuracy.

The MCP server

ZoneFoundry runs a relay (a single Python/aiohttp process) that fronts both the LAN bridge and the Sonos cloud. Exposing it as an MCP server was a few hundred lines: 23 tools — play_music, search_music, group_rooms, set_volume, announce, set_reminder, now_playing, undo_last and friends. Auth is a bearer key you generate in the app's Settings; there's no OAuth and no open-source repo yet.

Connect it from Claude Code in one line:

claude mcp add --transport http zonefoundry https://relay.zonefoundry.dev/mcp --header "Authorization: Bearer <your key>"
Enter fullscreen mode Exit fullscreen mode

It's also listed in the official MCP registry as dev.zonefoundry/sonos, and works with ChatGPT or any client that speaks streamable HTTP.

What it feels like: "Hey Claude, put something mellow on downstairs and remind me at 7 to take the laundry out." The speakers group, a playlist starts, and a reminder is set — three tools, one sentence. It's the first time the "AI in your home" pitch felt real to me, and it's only possible because the relay is already the thing that knows how to talk to the speakers.

Honest limits

  • EQ / alarms / battery / line-in are LAN-only (see above).
  • The cloud API has a per-household quota; the app is careful about polling, but an over-eager MCP client could burn it.
  • No Android, no open-source repo yet.

App Store: https://apps.apple.com/app/apple-store/id6775692838?pt=128979813&ct=devto&mt=8 — free, iOS 18+, no account needed on your Wi-Fi. I read every bug report.

Top comments (0)