Skip to main content
Glama
Massage Chair MCP

Massage Chair MCP

by ethanntann

Massage Chair MCP

CI License: MIT

An AI assistant that can give you a massage.

This is an MCP server that lets an AI agent such as Claude control an OSIM uDiva3 massage chair over Bluetooth LE. Ask for "something to help me wind down" and the agent picks a program, reclines the seat and starts it; ask for "kneading on my shoulders, a bit harder" and it drives the rollers directly. The chair has no public API, so I reverse-engineered its Bluetooth protocol from packet captures of the official phone app.

The problem, and why

I was curious about MCP servers and whether agent tools could control physical hardware, not just files and web APIs. Most agent demos stay on a screen. I wanted to bridge the gap between AI agents and hardware, and to have a physical demonstration of what an agent can do in the real world: something you can sit in and feel respond to a sentence.

That meant solving three problems:

  1. No API. The chair only talks to OSIM's app, over an undocumented BLE protocol.

  2. Hardware is slow and stateful. The seat takes up to 30 s to move, some commands are toggles, and the chair drops back to idle if it stops hearing from you. A tool call that returns "done" has to mean the chair really did it.

  3. Agents make mistakes. The tools have to be hard to misuse, and an agent (or a prompt injection) must not be able to leave the chair running.

Related MCP server: mcp-ble-bridge

How it works

 Claude / any MCP client
        │  stdio (JSON-RPC)
        ▼
 server.py ─────────── 25 tools: presets, manual techniques, seat, custom routines
        │                 enum-typed parameters, read-only vs actuating annotations
        ▼
 custom_presets.py ─── routines: validated JSON steps, run in the background
        │
        ▼
 udiva_driver.py ───── one BLE session: handshake, 0.7 s keepalive,
        │                 one write at a time, one operation at a time,
        │                 every command confirmed from status frames
        ▼
 protocol.py ───────── 4-byte commands + checksum, 14-byte status frame layout
        │
        ▼  BLE GATT (bleak): write fff2, notify fff1
 OSIM uDiva3 chair
  • Protocol (protocol.py): commands are [b0 b1 b2 checksum] written to characteristic fff2; the chair streams 14-byte status frames on fff1 carrying a motor flag, a seat-travel flag, the running program and an echo of the last command. Every byte is pinned by tests. How I decoded it is in docs/protocol.md.

  • Driver (udiva_driver.py): an asyncio session over bleak. It finds the chair by name or address, runs the handshake, keeps the session alive, and turns each request into a command loop that waits for the chair's telemetry to confirm it.

  • Routines (custom_presets.py): user-defined sequences ("knead the shoulders at 4 for five minutes, then move down to the lumbar") stored as JSON and run in the background, so the agent can check on them or stop them.

  • MCP server (server.py): FastMCP tools with instructions that steer the agent toward the chair's built-in programs, which are the most reliable, and toward manual control only when asked.

Results

What

Result

Protocol decoded

4-byte command format and checksum, 14-byte status frame, 18 factory programs, seat posture, manual techniques, 3D intensity, legs

Source material

4 PacketLogger captures of the OSIM app (~24,000 log lines), one action at a time, cross-referenced with app screens

Tools exposed

25 (presets, manual techniques, seat positions, custom routines, status)

Built-in routines

5 multi-step routines (desk neck relief, full back descent, wind down, leg focus, manual test)

Tests

103, offline, against a simulated chair (pytest), on every push (CI)

Key decisions

  • Confirm from telemetry, never from sleeps. The first version used fixed waits and reported success while the seat was still moving or had never started. Now a toggle waits for its echo, a preset waits for a non-zero program id, and a seat move holds its command at the app's ~100 ms cadence until the motor flag shows the travel limit. Tools say when the chair didn't acknowledge, so the agent can tell the user the truth.

  • Match the app's timing exactly. The captures showed the app sends no heartbeats while it holds a motion command, and a heartbeat injected into that stream makes the seat stop and restart. The keepalive goes silent during motion.

  • One write, one operation at a time. All GATT writes go through a single lock with a timeout, because two in-flight writes can leave one waiting forever. High-level operations are serialised too, and stop cancels whatever is running or queued before sending STOP, so it works even in the middle of a 60 s positioning sequence.

  • The driver owns the state. Tapping and kneading are toggles on the chair. The driver tracks what it believes is on and only sends a toggle when the state must change; everything is reset if the Bluetooth link drops, so a reconnect starts from a known state.

  • Make tools hard to misuse. Parameters with a fixed set of values are enums in the schema, ranges are bounded, and the server instructions tell the agent which tool fits which request. Anything that changes what the chair is doing first cancels a running routine instead of fighting it.

Safety and security

The tools move a chair that someone is sitting in, and the agent calling them may have read untrusted text. So:

  • A time limit on every massage. The server stops the chair once a massage has run for 2 hours (configurable, 10 to 240 minutes). It's a hard cap rather than an idle timeout, because a factory program normally runs for a long time with no tool calls; the cap is what stops a forgotten session.

  • Bounded routines. At most 100 steps, 30 minutes per wait and 90 minutes in total. Names and descriptions, which are shown back to the agent later, are length-limited and can't contain control characters.

  • Clear tool annotations. Read-only tools are marked read-only, so a client can tell them apart from tools that move the chair. By default the agent runs the chair without a confirmation prompt, which is the point; a client can be set to ask before actuating tools if you prefer.

  • The right chair. A config file can pin the chair's Bluetooth address, so a nearby device spoofing its name can't be picked up.

  • Local only. The server speaks MCP over stdio; there is no network listener and nothing leaves your machine except Bluetooth packets to the chair.

  • Stop always works. stop cancels in-flight work first, and a cancelled routine sends STOP on its way out.

See SECURITY.md to report a problem.

Run it yourself

You need an OSIM uDiva3 (OS-8211), a computer with Bluetooth LE, Python 3.11+ and an MCP client such as Claude Desktop.

git clone https://github.com/ethanntann/massage-chair-mcp
cd massage-chair-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                      # offline, no chair needed
.venv/bin/python scan.py              # with the chair on: find its name

Add the server to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "osim-udiva3": {
      "command": "/absolute/path/to/massage-chair-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/massage-chair-mcp/server.py"]
    }
  }
}

Close the OSIM phone app first (the chair accepts one Bluetooth connection), restart Claude Desktop and ask for a massage. To try things without an agent:

.venv/bin/python run_routine.py                 # list routines and programs
.venv/bin/python run_routine.py --preset spa 120
.venv/bin/mcp dev server.py                     # MCP Inspector

Optional ~/.udiva_config.json: {"address": "..."} to pin the chair, {"name": "OS8211 ..."} for an exact name, or {"prefixes": [...]}, and {"max_massage_minutes": 120} to change the time limit. Custom routines are saved to ~/.udiva_presets.json.

Limitations

  • One chair model. Only the OSIM uDiva3 (OS-8211) has been decoded and tested. Other OSIM chairs likely use a different command set.

  • Partly decoded. Two factory program ids (0x50, 0x51) are unnamed in the app, and the meaning of some status bytes is still a best guess. running in get_status means "the program id is non-zero".

  • One connection. The chair accepts a single Bluetooth connection, so the phone app and this server can't be connected at the same time.

  • Run-state is a toggle. The driver tracks whether it has entered the chair's run state; if someone uses the chair's own remote meanwhile, the driver can't know.

  • Unauthenticated chair. The chair's protocol has no pairing or encryption, so anyone in Bluetooth range can control it when no one else is connected. That's the product's design and outside this project's control.

  • Tested on macOS. bleak also supports Linux and Windows, but I have only run it against the chair from a Mac.

License

MIT. OSIM and uDiva are trademarks of OSIM International; this project is not affiliated with or endorsed by OSIM. Use it at your own risk.

Layout

protocol.py          wire protocol: commands, checksums, status frame layout
udiva_driver.py      BLE session: connect, keepalive, confirmed operations
custom_presets.py    routine schema, validation, storage, runner
server.py            MCP server and tools
run_routine.py       command-line runner (no MCP)
scan.py              list nearby BLE devices
tests/               simulated chair + 103 tests
docs/protocol.md     how the protocol was reverse-engineered

Available Tools

25 tools
connect_chairA

Connect to the chair over Bluetooth and run the required handshake. Usually not needed — all action tools auto-connect. Call this explicitly only if you want to pre-warm the connection. The OSIM phone app must be disconnected (the chair allows only one Bluetooth connection).

Inputs: no named parameters. Returns: result

delete_custom_presetB

Delete a user-saved custom routine (built-ins cannot be deleted).

Inputs: name (required). Returns: result

disconnect_chairA

Disconnect from the chair over Bluetooth, freeing it for the OSIM phone app or another client. Stops any running routine first. Call connect_chair again to reconnect.

Inputs: no named parameters. Returns: result

enter_manual_modeA

Start a manual massage and position the chair, ready for technique steps.

PREFER a factory program (list_presets / start_preset) when one fits the user's intent — use manual only for specific technique/zone combinations or when the user explicitly wants manual control.

This drives the chair to the massage position and deploys the rollers (auto shoulder-detect), then settles. It does NOT start any technique by itself — after this, turn on a technique (set_kneading/set_tapping) to actually start the rollers, then adjust rolling / zone intensity / shoulder position.

Args: area: 'back' for a Back Body roller massage (default), or 'head_neck' for a Head & Neck (V-grip) massage.

Powers on first if needed. Stops any running custom routine. Takes up to ~60s while the chair positions.

Inputs: area. Returns: result

get_custom_presetB
Read-only

Show the step-by-step definition of a custom routine as JSON.

Inputs: name (required). Returns: result

get_statusA
Read-only

Report the chair's state: connected, powered, running, program id, which manual techniques are active, and the custom routine (running, or how the last one ended).

Inputs: no named parameters. Returns: result

list_custom_presetsA
Read-only

List user-defined and built-in custom massage routines (distinct from the chair's factory presets).

Inputs: no named parameters. Returns: result

list_presetsA
Read-only

List the built-in factory massage programs with a short hint for each.

PREFER these over manual/custom control when one matches the user's intent — they are the most reliable (the chair positions and sequences them itself).

Inputs: no named parameters. Returns: result

power_offA

Stop all massage (including a running custom routine) and take the chair out of its run-state.

Inputs: no named parameters. Returns: result

power_onA

Move the chair into its active run-state so it's ready to start a program. (The chair is already powered at the wall — this is the 'begin' toggle, not a true power switch.) Auto-connects if not already connected. Usually not needed explicitly: start_preset and enter_manual_mode do this themselves.

Inputs: no named parameters. Returns: result

quick_startA

One-shot: connect (if needed), power on, and start a preset program.

Args: preset: a preset name (default 'spa'), or 'manual' for a manual back massage.

Inputs: preset. Returns: result

return_to_sofaA

Return the chair to its default sofa/resting position (backrest up, footrest down). Stops any running massage/routine first. Takes up to ~35s while the seat moves.

Inputs: no named parameters. Returns: result

run_custom_presetA

Start a custom routine. It runs in the background so you can check status or stop it at any time. Connects/powers on first if needed.

Inputs: name (required). Returns: result

save_custom_presetA

Save a custom massage routine.

Args: name: a short name (e.g. 'my_evening'). steps_json: a JSON array of step objects. Supported actions: {"action":"manual","area":"back"} (or "head_neck"; positions the chair + deploys the rollers) {"action":"seat_sofa"} / {"action":"seat_upright"} / {"action":"seat_recline"} (seat posture only) {"action":"tapping","on":true|false} {"action":"kneading","on":true|false} {"action":"rolling","level":"off|partial|full"} {"action":"intensity","zone":"shoulder|back|lumbar","level":0-5} {"action":"position","value":1-5} (shoulder roller height) {"action":"vgrip","on":true|false} {"action":"leg_kneading","level":"off|low|high"} {"action":"leg_vibration","level":"off|low|high"} {"action":"wait","seconds":N} {"action":"preset","name":"spa"} {"action":"stop"} description: optional human description.

Pattern that works: start with {"action":"manual","area":"back"} (it positions the chair and deploys the rollers), then turn on an ENGAGING technique FIRST — {"action":"kneading","on":true} (or tapping) — which is what actually starts the rollers. Only after that do rolling / intensity / position adjustments take effect.

Inputs: name (required), steps_json (required), description. Returns: result

set_kneadingA

Turn back KNEADING on/off (combinable with tapping and rolling). Requires manual mode.

Inputs: on (required). Returns: result

set_leg_kneadingC

Set leg/calf kneading: 'off', 'low', or 'high'.

Inputs: level (required). Returns: result

set_leg_vibrationC

Set leg/foot vibration: 'off', 'low', or 'high'.

Inputs: level (required). Returns: result

set_rollingA

Set back ROLLING. level: 'off', 'partial', or 'full'. Combinable with tapping and kneading. Requires manual mode.

Inputs: level (required). Returns: result

set_shoulder_positionA

Set the shoulder roller height, 1 (lowest) to 5 (highest). Requires manual mode.

Inputs: position (required). Returns: result

set_tappingA

Turn back TAPPING on/off (combinable with kneading and rolling). Requires manual mode.

Inputs: on (required). Returns: result

set_vgripA

Turn the head/neck V-grip on/off. Requires manual mode. Rollers take a few seconds to reach the neck.

Inputs: on (required). Returns: result

set_zone_intensityA

Set 3D roller intensity for a back zone (requires manual mode with a technique active).

Args: zone: 'shoulder', 'back', or 'lumbar'. level: 0 (off) to 5 (max).

Intensity scales whichever technique is active at that zone; the shoulder zone is the most reliably responsive.

Inputs: zone (required), level (required). Returns: result

start_presetA

Start a named built-in massage program. Powers on first if needed and confirms the program engaged. Stops any running custom routine.

Args: name: e.g. 'spa', 'deep_tissue', 'sweet_dreams', 'shoulders_care', 'lumbar_delight', 'sports_recovery', 'nap', 'detox', 'gentle'. Use list_presets for the full set.

Inputs: name (required). Returns: result

stopA

Stop the current massage — a factory program, manual massage, or custom routine — and return the chair to idle (it stays powered, ready for another program).

Inputs: no named parameters. Returns: result

stop_custom_presetA

Stop a running custom routine and bring the chair to idle.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 25 tools

    Disambiguation3/5

    There are three overlapping start paths (start_preset, quick_start, run_custom_preset) and three overlapping stop paths (stop, power_off, stop_custom_preset), and stop already claims to stop custom routines, making stop_custom_preset largely redundant. The fine-grained set_* technique tools are clearly distinct, and the descriptions do explain the power_on/power_off vs stop nuance, but an agent still has to reason carefully to pick the right start/stop tool.

    Naming Consistency4/5

    Mostly a consistent verb_noun snake_case scheme: get_status, list_presets, start_preset, set_kneading, save_custom_preset, delete_custom_preset, connect_chair. Minor deviations are the bare 'stop' and the vaguer 'quick_start'/'power_on' pair, but overall the pattern is predictable.

    Tool Count3/5

    25 tools is heavy for a single massage chair. The eight set_* technique setters are justified by the hardware, but the connection lifecycle (connect_chair/disconnect_chair, described as usually unnecessary) and the six custom-preset management tools push it past a comfortable scope.

    Completeness4/5

    Lifecycle coverage is strong: power/connect, status, factory presets, manual positioning plus all techniques, custom preset CRUD and execution. The notable gap is seat posture adjustment (seat_sofa/seat_upright/seat_recline) which is only reachable as a step inside a saved custom routine, not as a direct tool.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to control Bluetooth Low Energy devices remotely through a WebSocket and Web Bluetooth bridge, exposing tools for vibration, suction, licking, pulsing, and status checks.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables natural-language control of DK-META2 devices through local BLE for vibration, linear extension, and rotation. It also supports scanning, connecting, status checks, and safe stop/disconnect operations without cloud access.
      8
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables ChatGPT to control a SVAKOM SA697A device pair through a remote MCP server that relays commands over a phone-side Web Bluetooth bridge, with all safety rules enforced in code rather than by the AI.
      MIT