mcp-server-sofabaton

An MCP server for Sofabaton X1, X1S and X2 universal remote hubs. It lets an MCP client such as Claude start and stop activities, press remote buttons, send macros, favorites and device commands, find the remote, and read the presses of buttons you've bound to it.

All three models work through sofabaton-x-server. An X2 can also be reached over MQTT, either on its own or alongside the server. That adds live activity state, and keeps the hub controllable while the Sofabaton app is open. Every response tells the model which model it's talking to and what that hub can and can't do.

Status: alpha, looking for testers. Tested on one X2 over MQTT (see Tested on). The sofabaton-x-server path, and so every X1 and X1S, has run only against the simulator. If you have a Sofabaton hub, a report of what does and doesn't work on yours is the most useful thing you can send: open a hardware report.

Not affiliated with Sofabaton.

Tested on

Seen working on that X2 (2026-10-16): listing activities, devices, buttons, macros and favorites; starting an activity and powering it off, with the hub's confirmation; hard buttons (VOL_UP); a macro; favorites on two different devices; holding presses until the power macro has settled (about 5 s here, inside the 6 s window); and presses of a button bound to a Wifi Device arriving on <MAC>/up.

Seen not working, and handled: the X2 never answers a request for a device's own command list over MQTT, so device commands over MQTT are refused up front with what would enable them (sofabaton-x-server). And a burst of a dozen or so unanswered requests left that X2 still publishing state but answering nothing until it was power-cycled; nothing in the server sends requests like that.

Not tested on hardware yet: the X1 and X1S, sofabaton-x-server with any hub, an X2 on both paths at once, more than one hub, brokers other than Mosquitto, and other firmware. Each detail the code relies on is a named assumption with its source and status in PROTOCOL.md; HARDWARE_VALIDATION.md is the checklist for confirming them on your hub.

What works with which hub

MQTT is X2-only. The X1 and X1S have no MQTT; on those models, the server is the only way in and everything in the first three rows works through it. get_status reports this as model, capabilities and limitations, so the model can plan around it. For example, on an X1S it says "This is an X1S: live activity state, control while the Sofabaton app is open, and MQTT presses need an X2."

How it reaches the hub

Claude ──► mcp-server-sofabaton ──┬──► sofabaton-x-server ──► hub (X1, X1S, X2)
          (picks a path per call) └──► MQTT broker ◄────────► hub (X2 only)

• Through sofabaton-x-server (any model). Sofabaton publishes no API. The sofabaton-x library reverse-engineers it by sitting between the hub and the official app as a proxy, so one process owns the hub at a time. sofabaton-x-server is that process, with a REST API. Going through it means many clients can share the hub. It also means a model can only reach the control routes: editing, erasing and restoring the hub need a token this project never holds.
• Over MQTT (X2). The X2 keeps its own connection to the broker you set in the Sofabaton app (Me → Connect to Home Assistant). It answers list requests and takes commands on topics under its MAC, and it announces every activity change. This doesn't go through the proxy, so it keeps working while the app holds it.

With both configured, each call uses the server when it's in control mode and MQTT otherwise. Names are resolved on whichever path is used, so ids never cross from one to the other.

Install

python -m venv ~/.venvs/sofabaton && . ~/.venvs/sofabaton/bin/activate
pip install "mcp-server-sofabaton[mqtt]"     # or without [mqtt] for server-only (X1/X1S, or an X2 without MQTT)

From source instead (for the newest code, or to run the tests):

git clone https://github.com/SDNick484/mcp-server-sofabaton.git && cd mcp-server-sofabaton
python -m venv .venv && . .venv/bin/activate
pip install -e ".[mqtt,dev]" && pytest

Requires Python 3.11+. The [mqtt] extra adds one dependency, aiomqtt (which brings paho-mqtt).

Claim sofabaton-x-server. Open its control panel and set up an admin account (Server settings > Access). Until you do, it lets anyone on the LAN edit and erase hubs. doctor warns while it's unclaimed.

Configuration

Environment variables (an MCP client may not pass your shell's environment, so set them in the client's config):

There is deliberately no sofabaton-x-server token setting. Bad values are reported by name at startup and by doctor, rather than failing later.

Typical setups:

# X1 / X1S, or an X2 without MQTT
SOFABATON_URL=http://192.168.1.70:8480

# X2, both paths (recommended)
SOFABATON_URL=http://192.168.1.70:8480
SOFABATON_MQTT_URL=mqtt://sofabaton@192.168.1.10:1883
SOFABATON_MQTT_PASSWORD_FILE=/etc/mcp/sofabaton-mqtt.pw

# X2, MQTT only (no sofabaton-x-server)
SOFABATON_URL=none
SOFABATON_MQTT_URL=mqtt://sofabaton:secret@192.168.1.10:1883
SOFABATON_MQTT_MAC=02:AB:34:CD:56:EF

First contact

mcp-server-sofabaton doctor     # each layer, with a hint for whatever fails
mcp-server-sofabaton check      # the model, the path, capabilities, and the names the model will use
mcp-server-sofabaton call start_activity activity="Watch Shield"    # one tool, as the model calls it

doctor checks the server (reachable, version, claimed, hub session, mode, identity, catalog) and MQTT (login, the X2 answering on its topics). If the X2 doesn't answer on the uppercase-MAC topics, it tries lowercase and tells you. doctor --listen 30 prints everything the X2 publishes while you press keys on the remote. doctor --dump DIR saves a redacted capture for tests/fixtures/recorded/.

Use it with an MCP client

Local (stdio): Claude Code and Claude Desktop launch it themselves.

{
  "mcpServers": {
    "sofabaton": {
      "command": "/path/to/mcp-server-sofabaton/.venv/bin/mcp-server-sofabaton",
      "env": {
        "SOFABATON_URL": "http://192.168.1.70:8480",
        "SOFABATON_MQTT_URL": "mqtt://sofabaton:secret@192.168.1.10:1883"
      }
    }
  }
}

For Claude Code: claude mcp add sofabaton -e SOFABATON_URL=http://192.168.1.70:8480 -- /path/to/.venv/bin/mcp-server-sofabaton.

As a service (Streamable HTTP), to share one instance between Claude Code, Claude Desktop and the mobile app through a Cloudflare Tunnel with Cloudflare Access in front:

CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com CF_ACCESS_AUD=<aud tag> \
  mcp-server-sofabaton serve --http --public-host mcp.example.com    # 127.0.0.1:8714/sofabaton/mcp

Every request must carry a valid Access JWT (Cf-Access-Jwt-Assertion). The checks and the flags are documented in src/sofabaton_mcp/remote.py. The Host-header (DNS-rebinding) checks stay on even with --bind 0.0.0.0: for LAN clients, also pass --public-host <this machine's LAN IP>.

As an OpenRC service on Alpine (e.g. a Proxmox LXC)

deploy/alpine/ installs it the same way as mcp-server-webos and -harmony, so all three can share an LXC: a venv in /opt/mcp-server-sofabaton (with the [mqtt] extra), a mcp-sofabaton system user, every setting in /etc/mcp-server-sofabaton/env, and supervise-daemon restarting it if it exits. Keep the broker password out of the env file: put it in /etc/mcp-server-sofabaton/mqtt-password (0640 root:mcp-sofabaton) and set SOFABATON_MQTT_PASSWORD_FILE to that path.

git clone https://github.com/SDNick484/mcp-server-sofabaton.git && cd mcp-server-sofabaton
sh deploy/alpine/install.sh                                # as root; re-run to upgrade
vim /etc/mcp-server-sofabaton/env                          # SOFABATON_URL and/or SOFABATON_MQTT_*, Access
su -s /bin/sh mcp-sofabaton -c '/opt/mcp-server-sofabaton/run.sh doctor'
rc-update add mcp-server-sofabaton default && rc-service mcp-server-sofabaton start

Because every setting is an environment variable, run.sh takes a subcommand and runs it with exactly the service's environment: run.sh doctor, run.sh check, run.sh call get_status. Logs are in /var/log/mcp-server-sofabaton/server.log. CI runs deploy/alpine/smoke-test.sh in a stock python:3.12-alpine container: install, the test suite on musl, run.sh doctor, the service under OpenRC, and an MCP call over HTTP reaching a simulated X2 on both paths.

Tools

Actions return {outcome: done | unchanged | dry_run, detail, via, sent}. sent lists the exact requests or publishes, with the MAC shown as <MAC>. When something can't work on this hub, the error says why and what would enable it.

A session against the simulator

An X2 with both paths. Someone opens the Sofabaton app partway through, and the server switches to MQTT. (Output from simulate, trimmed.)

> get_status
  {"model": "X2", "via": "server", "running_activity": null, "transition": null,
   "capabilities": ["catalog", "activities", "buttons", "commands", "presses", "find_remote",
                    "hub_info", "live_activity_state", "control_while_app_open"],
   "limitations": [], ...}

> start_activity {"activity": "Watch Shield"}
  {"outcome": "done", "detail": "Start Watch Shield", "via": "server",
   "sent": ["POST /api/v1/hubs/a1b2c3/activities/101/start"]}

> press_button {"button": "VOL_UP", "repeat": 3}
  {"outcome": "done", "detail": "Press VOL_UP x3 on activity Watch Shield", "via": "server", ...}

# (someone opens the Sofabaton app: sofabaton-x-server goes to observe mode)

> start_activity {"activity": "Listen to Music"}
  {"outcome": "done", "via": "mqtt",
   "detail": "Start Listen to Music. The X2 announced it early; its power macro may run for a
              few more seconds (presses wait 6s).",
   "sent": ["publish activity/<MAC>/activity_control_down {\"data\": {\"activity_id\": 102, \"state\": \"on\"}}"]}

> send_command {"command": "Input HDMI 2", "target": "Onkyo Receiver"}
  ERROR: The X2 just changed activity and its power macro may still be running; a press now
  could interrupt it. Try again in 5s (SOFABATON_MQTT_SETTLE_S sets this window).

> get_status
  {"model": "X2", "via": "mqtt", "running_activity": "Listen to Music",
   "transition": "power macro may still be running (presses wait 5s more)",
   "capabilities": ["catalog", "activities", "buttons", "commands", "presses", "hub_info",
                    "live_activity_state", "control_while_app_open"],
   "limitations": ["The Sofabaton app holds sofabaton-x-server's proxy (observe mode): commands
                    go over MQTT meanwhile, and find_remote waits until the app is closed."], ...}

The same calls on an X1S go through the server, and limitations says the MQTT features need an X2.

The remote as an input

A "Wifi Device" on the hub is a virtual device whose commands do nothing but report the press. On the X2 it can report to <MAC>/up on your broker, and on any model it can report over HTTP to sofabaton-x-server. Bind one to a key (say, a long press of a color button) and get_recent_presses sees it. A remote button can then mean "ask the assistant" or "run my bedtime routine" to an agent that watches for it. Wifi Devices are set up in the Sofabaton app or the server's control panel: that's editing the hub, which this server doesn't do.

Safety design

• No token, so no edits. sofabaton-x-server lets anyone read and control, and requires a token for editing, deleting, erasing and restoring. This project never holds one.
• A local route allow-list too. The REST client can only make GETs and the four control POSTs (send, activity start/stop, find-remote). Anything else raises before a request leaves the process. test_openapi_contract.py checks that the allow-list matches exactly those routes in the server's published API.
• MQTT topics are fixed. Only the topics in protocol.py are ever published to, with payloads built from names resolved against the hub's own lists.
• Names, not ids. The model never supplies an id. Buttons are an enum. POWER_ON and POWER_OFF are left out, so starting and stopping always go through the tools that confirm.
• Confirmation, not trust. accepted: true means the hub took the frame. Starts and stops wait for the hub to report the change.
• Don't interrupt a macro. Over MQTT the X2 announces a change at the start of its power macro and never says when it's done, so presses wait out a settle window.
• Rate limits and caps. Per call: at most 10 repeats, 100-2000 ms apart. Across calls (a model in a loop): 20 presses in a burst, then 4 a second; 4 activity changes in a burst, then one per 15 s. A call over the limit is refused whole, never half-sent.
• Dry run. serve --dry-run (or call --dry-run) reads the hub and reports what it would send.
• Logs are redacted: IP addresses and MACs (unless --no-redact), and always secrets (passwords in URLs, JWTs, bearer tokens, keys). They go to stderr; stdout is the MCP transport.
• Every tool has a title and explicit MCP annotations. Nothing is destructive.

Troubleshooting

Development

pip install -e ".[dev]"
pytest -q           # everything, no hardware: fakes for the server, the broker and the X2
ruff check . && ruff format --check . && mypy

The simulator runs the same fakes as real services, so you can point a client (or doctor) at them:

mcp-server-sofabaton simulate                 # X2: fake server + broker + X2; type `help` at sim>
mcp-server-sofabaton simulate --model X1S     # server only
mcp-server-sofabaton simulate --no-server     # X2 over MQTT only

It prints the export lines for another terminal. At its sim> prompt you act as the physical remote (off, start <activity>, key <device> <key>) or change the scene (app on puts the server in observe mode).

The MQTT tests use an in-package broker by default. To run them against mosquitto, as CI does:

docker compose -f dev/compose.yaml up -d
MQTT_TEST_BROKER=mqtt://127.0.0.1:1883 pytest -q tests/test_mqtt.py tests/test_tools.py tests/test_tooling.py -rs

What the tests cover:

Verification status

These are the protocol assumptions the code depends on. hardware-verified means seen on a real hub; the rest are verified against the simulator only (details and sources in PROTOCOL.md):

test_assumptions.py fails if this table and assumptions.py disagree.

Roadmap

• Validate on hardware (HARDWARE_VALIDATION.md)
• Push instead of poll: surface activity changes and presses as MCP resource updates
• Publish to PyPI and the MCP registry

License

MIT. See LICENSE.