bodybridge

Connect embodied devices to cloud AI via MCP. 具身 × 云端 MCP 桥

Zero API cost · No PC required · Fully self-hosted

One wide bridge, not many narrow ones.

What is this

bodybridge is an open-source, self-hosted MCP bridge that lets embodied devices — StackChan, Raspberry Pi, ESP32, and more — be driven by an AI. Any MCP-compatible client can connect; through the claude.ai connector it runs on your existing subscription, so the brain (LLM inference) costs nothing extra.

Instead of writing a separate bridge for every device, bodybridge gives you one bridge with a standard slot: implement three methods, and your device is in.

Why bodybridge:

• Zero API cost (on the claude.ai path) — Runs on your existing Claude subscription; no extra token billing for the brain (LLM inference). Other MCP clients can connect too, but as of now claude.ai is the only path where a personal subscription covers programmatic use — others bill per token. See Deploy.

• No PC required — Cloud-hosted. No need to keep a machine running at home.

• Fully self-hosted — Your data and keys stay with you.

Related MCP server: stackchan-relay

Architecture

Four layers, each with one job:

Design philosophy: flexible at the top, solid in the middle, rule-based at the bottom.

A puppy that doesn't understand you tilts its head — it doesn't run wild. 小狗听不懂你说话，会歪头看你，而不是乱跑。

When the AI can't understand, or the device can't comply, the bridge says so honestly instead of guessing. That refusal is the safety mechanism.

What V1 does

V1 lets the AI control device actions — minimal, readable, stable, zero dependencies.

Quick Start

bodybridge is an MCP bridge: it connects embodied devices (ESP32, Raspberry Pi, StackChan…) to any MCP-compatible AI client. claude.ai is the primary path — and the only one where the AI runs on your existing subscription with no extra API bill (see Deploy).

This section gets a working bridge running on your own machine in about five minutes. Connecting it to an AI client comes after, under Deploy.

Prerequisites

• Python 3.10+

• uv (pip install uv, or see uv's docs)

Steps

# 1. Clone
git clone https://github.com/alice-jin-dev/bodybridge.git
cd bodybridge

# 2. Configure — copy the template and fill in the three required values
cp .env.example .env
#    Then open .env and set all three (the bridge won't start until you do):
#
#      BODYBRIDGE_TOKEN      — the JWT signing secret. Generate a strong one:
#          python -c "import secrets; print(secrets.token_urlsafe(32))"
#
#      BODYBRIDGE_PASSWORD   — the password gate for /oauth/authorize.
#          Any non-empty string works; a strong random one is recommended
#          (you can use the same command as above).
#
#      BODYBRIDGE_PUBLIC_URL — the bridge's public base URL. Not a secret.
#          For a local run:  http://127.0.0.1:8000
#          No trailing slash, no /mcp — the bridge appends that itself.
#
#    The bridge auto-loads .env on startup, so no extra flags are needed.

# 3. Install dependencies
uv sync

# 4. Run
uv run python server.py

If it started, you'll see:

[bodybridge] starting on 0.0.0.0:8000 (port source: BODYBRIDGE_PORT)

(You may also see a warning that BODYBRIDGE_DEVICE_TOKEN is not set — that's expected for a local run; the /device endpoint stays disabled until you set it, which is what you'll do when you attach a device.)

That's the bridge itself running. It has no device attached yet — that's expected. get_status will report offline until a device connects.

Not seeing it start? If the bridge exits immediately, you most likely left BODYBRIDGE_TOKEN, BODYBRIDGE_PASSWORD, or BODYBRIDGE_PUBLIC_URL empty — all three are required.

Deploy

For an AI client to reach your bridge, it needs to be on a public HTTPS URL. In short: deploy to any platform that gives you HTTPS (the project runs on Zeabur), set the same variables in the platform's Variables panel (not a .env file), plus BODYBRIDGE_PUBLIC_URL so OAuth discovery works. The full walkthrough is in Deployment.

With claude.ai (recommended). Add the bridge as a custom connector in claude.ai. Because the AI runs on your existing claude.ai subscription, this path adds no per-token API bill — your device gets a brain for the price of a subscription you already pay for.

With other MCP clients. The bridge speaks standard MCP, so any MCP-compatible client can connect to it with little or no change on the bridge side. (Note: only the claude.ai path is subscription-covered; other clients bill on their own terms.)

Bring your own device

Want to connect real hardware? See Connecting a device. You don't write an adapter and you don't download anything — your device just speaks the bridge's protocol. On an ESP32 that's five steps to a blinking LED.

The two guides split the job: Connecting a device is the general one — the protocol any device has to speak. The firmware guide is ESP32-specific — the sketch itself, the Arduino IDE setup, and flashing it to the board.

Deployment

Upgrading an existing deployment? Authentication changed from a static token to OAuth 2.1 in this version. See MIGRATION.md for what's different and what you need to do.

The bridge has to run on a cloud host that is publicly reachable over HTTPS. A client's servers — Anthropic's, on the claude.ai path — perform OAuth discovery against the bridge from the outside, and custom connectors require a certificate a public client will trust. A self-signed cert or a LAN-only address will not do. Which host you use is up to you; the bridge is not tied to any platform.

The shortest path: deploy to a host that gives you HTTPS, set the three required variables in its variables panel, then set BODYBRIDGE_PUBLIC_URL to the domain it assigned you and restart. Most platforms only hand out that domain after the first deploy, so expect to start the bridge twice.

BODYBRIDGE_PUBLIC_URL must match, character for character, the URL you type into your MCP client when adding the connector. A mismatch fails resource validation and the connection is rejected — while the bridge keeps running and logging nothing unusual. Write it with no trailing slash and no /mcp path.

→ Deployment — the full walkthrough: what to require of a host, a worked example, three read-only checks that tell you it worked, and what each failure mode looks like.

Bring your own device

Any device you can program — ESP32, Raspberry Pi, anything that can run a WebSocket client — connects by speaking the bridge's protocol. You don't write an adapter and you don't download anything: the generic WebSocket adapter already ships inside the bridge.

→ Connecting a device — the five-step ESP32 path, the minimum contract for any other device, and what to check when it won't connect.

Writing an adapter is a different job, and only for devices that can't run a WebSocket client at all — a finished commercial product, or hardware that speaks its own protocol.

Before a device connects

Until a real device is connected, the three device tools return an offline result (for example, get_status reports that the device isn't connected). This is the correct, healthy state — not an error. It means the bridge is up and waiting for a device; it does not mean anything is misconfigured. Once your device connects to the /device endpoint, the tools begin reflecting its real state.

Tech stack

• Python 3.10+

• MCP official SDK (FastMCP)

• MCP specification: 2025-11-25

• Transport: streamable-http, stateless by default

Architecturally a thin core with a plugin slot — the microkernel pattern.

More features isn't always better — for those who don't need them, they're just weight.

Changelog

Release history is in CHANGELOG.md.

License

MIT

Author

alice-jin-dev