It lets an AI agent discover, monitor, and control ctrlPi GPIO agents (Pi, Pico, ESP32) over their REST APIs.
List configured agents, probe online status, and trigger LAN rescans for new hardware.
Read, write, toggle, pulse, scan, and configure GPIO pins, including watched pins.
Configure and read named sensors that run scripts on the agent.
List, read, create/overwrite, delete, run, and lock script files on agents.
Read and write agent configuration, including API keys, webhooks, logging, and full config loads/resets.
Restart or reboot agents, upgrade agents to the latest release, and read recent agent logs.
Provides tools to control GPIO agents running on Raspberry Pi (pi-gpio-api) over HTTP, including reading and writing GPIO pins, configuring pin modes and pull resistors, scanning hardware pins, reading sensors, managing agent configuration, logs, restarts, and upgrades.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-bridge turn on the LED on garage-pi"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that lets an AI agent (e.g. Claude Desktop) control one or more GPIO agents through an ordinary conversation, by calling their REST API over HTTP.
Runs on a Mac, a Raspberry Pi, or any Linux box, secured with API key authentication, zero npm dependencies.
Looking for the GPIO servers themselves, or Apple HomeKit and Google Home? See the Related projects below.
This app acts as a pure API proxy. It is a thin MCP front-end: every tool targets an agent and proxies the request to that agent's REST endpoints, forwarding that agent's own Api-Key.
[MCP client: Claude Desktop / mcp-remote]
│ MCP (STDIO or Streamable HTTP /mcp)
▼
[mcp-bridge]
│ REST (GET/POST, Api-Key per agent)
├──────────────→ [garage-pi 192.168.1.50:8314] (pi-gpio-api)
└──────────────→ [shed-pico 192.168.1.51:8314] (pico-gpio-api)Node.js 20 or newer, with node and npx on your PATH. If you do not have it, take the LTS build from nodejs.org. Nothing else is needed: the MCP protocol (JSON-RPC 2.0 over stdio or Streamable HTTP) is hand-rolled on Node built-ins, so the package has zero dependencies.
You also need at least one GPIO agent reachable on your LAN, a pi-gpio-api Pi, a pico-gpio-api Pico W, or an esp32-gpio-api ESP32. This bridge acts strictly as a control plane to drive them remotely.
Related MCP server: jwx-mcp
Let Claude Desktop fetch and start the app itself, in one step with npx, which downloads the published package and runs it without installing anything.
Open Claude Desktop's Settings → Developer → Edit Config, which opens ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or the equivalent file on Windows or Linux, and add the server under mcpServers:
{
"mcpServers": {
"ctrlpi": {
"command": "npx",
"args": ["-y", "@ctrlpi/mcp-bridge"]
}
}
}Restart Claude Desktop and the tools are there. Ask it what agents you have and it will call mcp_agents_list; from then on it can read pins, drive outputs, and configure the agents in plain conversation.
The first launch sweeps your local /24 and writes every agent it finds to ~/.ctrlpi/agents-config.json. By default, newly discovered agents are recorded using their shipped default keys. (You can append --rotate-keys to the args array to automatically generate and apply a new random key to each one.)
The sweep repeats on every launch and every hour after it, which is what picks up an agent switched on later and repairs the address of one that took a new DHCP lease (a Pico nearly always does on reset). Add --no-scan to turn that off once your setup has settled, and take it out again the day something moves.
Install it properly when you want to own the process, or when the bridge runs on a Pi and has to be reachable from Claude Desktop and other clients on different machines. Under npx the server lives and dies with the client that started it and is refetched as needed; installed, it stays in one place and you start and stop it yourself.
npm install @ctrlpi/mcp-bridge
cd node_modules/@ctrlpi/mcp-bridge
npm start -- --httpIt listens on port 8315 on every interface, so any client on the LAN reaches it at http://<host>:8315/mcp. Set mcp.api_key before you expose it: HTTP mode is key-gated, and the first caller to connect with a key of its own claims it (see Authentication). --local keeps the listener on loopback instead.
HTTP mode is intended for continuous background execution; a stdio server is started and stopped by the client that owns it. To leave the HTTP transport running on a Pi without a terminal open, start it under PM2:
npm install -g pm2 # if you don't already have it
pm2 startup # no need to repeat if already done
pm2 start server.js --name mcp-bridge -- --http
pm2 save--name mcp-bridge is not optional: PM2 would otherwise name the process after the script and call it server. mcp-bridge is the name the rest of the ctrlPi tooling looks for when it manages this process. The -- is not optional either, or PM2 reads --http as one of its own flags and starts nothing.
Run it with npm start from the installation folder (node_modules/@ctrlpi/mcp-bridge), passing flags after -- (npm start -- --http), or with npx -y @ctrlpi/mcp-bridge and no install at all. The flags below are identical either way, and one given without a valid value (say --port with no number) stops the server with an error.
stdio is the default and communicates directly over standard input/output: the transport is the process's own stdin and stdout, and the client that launched it owns both. Everything the server would print goes to stderr instead, because stdout is the protocol channel. This is the mode Claude Desktop uses.
--http serves Streamable HTTP at POST /mcp on port 8315, one above the agents' own 8314, for a client that cannot launch a local process or sits on another machine. It is a server: it stays up, holds a port, and requires mcp.api_key from every caller (see Authentication).
No environment variables are needed: everything is set with the flags below or in the config files.
Flag | Effect |
(none) | Runs the stdio MCP server, the default transport. |
| Serves Streamable HTTP at |
| Binds to loopback ( |
| Explicit bind address; wins over |
| Listen port (default |
| Replace the shipped default key on any agent still using it with a random one, and record the date under |
| Turn off the automatic LAN sweeps, at startup and hourly. A first run with no config still sweeps once, since there would be no agents at all otherwise. An explicit |
| Minutes between the automatic sweeps (default |
| Keep both config files in this folder instead of |
For the ordinary case, where Claude Desktop launches the server itself over stdio, use the npx form under Quick start. Substitute "command": "node", "args": ["<path>/node_modules/@ctrlpi/mcp-bridge/server.js"] if you installed it instead.
To reach a bridge over the network, start it in HTTP mode first (npm start -- --http), then connect through mcp-remote, passing mcp.api_key (your-mcp-key by default, see Configuration):
{
"mcpServers": {
"ctrlpi": {
"command": "npx",
"args": [
"-y", "mcp-remote", "http://<host>:8315/mcp", "--allow-http",
"--header", "Api-Key:your-mcp-key"
]
}
}
}--allow-http permits the connection over a trusted local network.
Pick one of the two, not both. Restart Claude Desktop after saving either.
Cursor takes the same JSON as Claude Desktop, for either form above. Put it in ~/.cursor/mcp.json, or in .cursor/mcp.json inside a project.
Claude Code speaks both transports directly, so no mcp-remote hop is needed. Pick one.
stdio, where Claude Code launches its own copy:
claude mcp add ctrlpi -- npx -y @ctrlpi/mcp-bridgeStreamable HTTP, attaching to a bridge already running with --http:
claude mcp add ctrlpi --transport http http://<host>:8315/mcp --header "Api-Key: your-mcp-key"Two independent keys are in play, and they are never the same one:
Key | Where it lives | What it does |
|
| Gates this server in |
|
| Each agent's own key, forwarded on every proxied REST call. Never sent to an MCP client. |
stdio mode needs no key at all: the transport is the process's own stdin/stdout, so whoever launched it already has that access.
While mcp.api_key is still the shipped your-mcp-key, the first caller to present a different key claims it: that key is written to mcp-config.json with the date under mcp.key_set, and from that moment it is the only key accepted. Just connect with the secret you want to use and it becomes the secret.
This is trust on first use, so the window is exactly as safe as your network during it: whoever reaches the port first sets the key. Set mcp.api_key by hand to skip the window, and keep --http off an untrusted LAN until a key is in place. Once claimed, the key only ever changes by editing the file.
No TLS. The HTTP transport speaks plain HTTP, so
mcp.api_keytravels as plaintext. That's fine on a trusted LAN, but don't expose port 8315 directly to the internet. If you need remote access, tunnel it.--localkeeps the listener on loopback. The key is exclusively read from theApi-Keyheader, keeping it out of shell history and proxy logs.
A request from a web browser is accepted only from a localhost or IP-address page (its Origin header), so a web page cannot reach the bridge through a domain pointed at your network (DNS rebinding). MCP clients that are not browsers send no Origin and are unaffected.
Every tool except mcp_agents_list takes an agent argument naming an entry from the shared ~/.ctrlpi/agents-config.json.
Tool | Description |
| List all configured agents with |
| Read a pin by number or name. Pass |
| Write |
| Configure a pin. Same fields as the agent's REST config endpoint. |
| List the GPIO pins that are currently being actively watched (emitting hardware interrupts/webhooks). |
| Scan every hardware pin (BCM 2-27 on a Pi, GP0-GP28 on a Pico, every usable pin of the chip on an ESP32). |
| Configure a named sensor. |
| Read one sensor by name, or every configured sensor merged into one object when |
| List the files in the agent's |
| Read one file from |
| Create or overwrite a file in |
| Run a file from |
| Read the agent's full config: |
| Update config fields, named ungrouped (the agent routes each into its group). Changing the agent's |
| Load a whole config onto the agent. Pass |
| Restart the agent's process. |
| Upgrade the agent to the latest release, then restart it. A Pi re-downloads the release and reinstalls dependencies; a Pico or ESP32 downloads the new files over WiFi and resets. |
| Read the last 50 lines of the agent's log. |
Tools return the agent's JSON response as text, or an Error: ... string flagged with isError when the agent is unknown, unreachable, or answers with an error status.
Where the config lives: in
~/.ctrlpi/, always - never next toserver.js, however you started it. Pass--config <folder>to keep both somewhere else; they are always named the same and always sit together.
Two files. Neither ships with the package: the first run builds both from a LAN scan, so there is no template to copy.
~/.ctrlpi/agents-config.json - the agents, shared with every other ctrlPi project:
{
"agents": [
{ "name": "garage-pi", "ip": "192.168.1.50", "port": 8314,
"api_key": "a1b2c3d4e5f60718293a4b5c", "key_set": "2026-08-20 14:23:13", "updated_at": "2026-08-20 14:23:13" },
{ "name": "shed-pico", "ip": "192.168.1.51", "port": 8314,
"api_key": "shed-pico-secret-key", "updated_at": "2026-08-20 14:25:00" }
]
}When reading shared agents, mcp-bridge also checks if /var/lib/homebridge/ctrlpi-agents-config.json exists; if so, it reads it (read-only) and reconciles agents whose updated_at date/time is newer. It never writes to the Homebridge config file.
~/.ctrlpi/mcp-config.json - what only this server owns:
{
"mcp": { "api_key": "your-mcp-key" },
"agents": { "whitelist": [], "blacklist": [] }
}Field | File | Description |
|
| Secret required to reach this server in HTTP mode. Ignored in stdio mode. Starts as |
|
| When |
|
| Optional. Agent names this server may drive: a whitelist keeps only those, a blacklist drops those, both means whitelist minus blacklist, neither means all of them. Tools exclusively see agents permitted by the filter, ensuring only approved agents can be addressed. |
|
| Unique name used to target the agent in every tool call. |
|
| LAN IP or hostname of the agent's REST server. |
|
| REST port (optional, default |
|
| That agent's own |
|
| When |
|
| Date and time the agent record was created or updated, UTC |
Both files are re-read on every tool call, so adding, removing or re-keying an agent by hand takes effect without a restart. The filter is applied only to what tools see: discovery always saves the full shared list, so narrowing it here strictly preserves other projects' agents in the shared list.
The agent list keeps itself current. Every start sweeps the local /24, and so does every hour after that, so an agent switched on later is picked up without anyone restarting anything. The sweep runs in the background, so the server answers at once; a tool that names an agent the sweep has not filed yet waits for it. --no-scan turns the automatic sweeps off.
Each sweep is one scan feeding three passes, in this order:
Repair the address of any agent that moved. Agents take new DHCP leases (a Pico nearly always does on reset), which otherwise breaks every call to it.
Rotate the key of anything still on the shipped default, with --rotate-keys only.
Add whatever is left that isn't on record yet.
Repair runs first on purpose: an agent that merely moved is not a new agent, and adding it before its address is fixed would file it twice, the second time as <name>-<octet>.
Newly found agents are filed under whichever key applies. Setup decisions are made autonomously using command-line flags, accommodating MCP clients that launch the server without a console.
It still accepts the shipped default key (your-secret-key). With --rotate-keys, a random key is written to the agent (POST /config/update), verified by reading back with it, then saved here with today's date in key_set. Without the flag the agent is recorded on the default key, untouched.
The default key is refused, so the agent already has a key of its own that this app has no way to read. It is saved without a key, requiring manual configuration of api_key.
--rotate-keys also revisits agents already on file that are still on the default key, so adding the flag later secures a setup that was first discovered without it. It is safe to leave on permanently: an agent that already has a key of its own is never touched, which makes repeat runs a no-op.
An agent's key is only ever changed when this app can save the result, so a rotation that cannot be recorded never happens - the alternative locks that agent out of every other ctrlPi tool.
A moved agent is adopted only after the old address stops answering, and it is checked with the public default key first - its own key is only ever offered once the old address is confirmed dead, so a device that merely took a familiar name is never handed that agent's key.
If two devices answer to one name, that is reported as a possible cyber attack. When the configured address is still alive it is treated as genuine and the other is renamed on the device (only if it accepts the default key); when it is also dead, nothing is changed - there is no safe way to tell which is which.
mcp-bridge is an inbound control plane only; it never receives the agents' webhooks, by design:
Push can't wake the model. MCP clients invoke the server, not the other way round; a webhook arriving here couldn't start a Claude conversation, so a listener wouldn't make the AI reactive. Reactive automation is the bridges' job (homekit-bridge :8316, matter-bridge :8317).
Lifecycle. In stdio mode the server only lives while the MCP client session is open, so events outside a session would be lost.
pi-gpio-api: Raspberry Pi GPIO REST server that reads inputs and drives outputs (and named sensors) over an HTTP API.
pico-gpio-api: Raspberry Pi Pico W port of the GPIO REST server, with the same endpoints, wire format, and auth.
esp32-gpio-api: ESP32 port of the GPIO REST server for MicroPython, with the same endpoints, wire format, and auth.
homebridge-ctrlpi: A Homebridge plugin that brings Raspberry Pi, Pico W, and ESP32 GPIO into Apple Home, by driving one or more GPIO agents over their REST API.
homekit-bridge (coming soon): Native Apple HomeKit bridge that exposes GPIO pins and sensors as HomeKit accessories, driven over the agents' REST API.
matter-bridge (coming soon): Matter bridge that exposes GPIO pins and sensors to any Matter platform (Apple Home, Google Home, Alexa, Home Assistant), driven over the agents' REST API.
ctrlpi-cli: Command-line interface for interacting with ctrlPi agents, with shared agent configuration.
ctrlpi-lab: A local browser dashboard for your ctrlPi setup. Test GPIO and sensor endpoints, watch webhook events, and tail agent logs.
pico-bay: Web app and MCP server for managing MicroPython and CircuitPython boards, such as the Raspberry Pi Pico and ESP32, over USB.
pi-bay (coming soon): A local web app and MCP server for Raspberry Pi boards over the network. Edit files, open a remote terminal, and manage your Pi remotely.
The MCP server includes an integration test suite that runs against a mock agent. Note: running the tests requires Python 3 installed locally for the mock server (mock_agent.py).
npm testRead the last 50 lines of agent's server log file.
Inputs: agent (required).
Restart agent's server process. Pass reboot=true to reboot the whole device instead (a Pi, Pico or ESP32); an agent running on a Mac ignores it and restarts the process.
Inputs: agent (required), reboot.
List configured agents (Pi, Pico or ESP32). Returns name, ip, port, online (live /hello probe), type (pi/pico/esp32), version, has_default_key, and last_updated_at (UTC "YYYY-MM-DD HH:MM:SS", when the agent list was last saved; every sweep saves it). Unreachable agents are included (online=false). The LAN is swept automatically every hour. Pass rescan=true to sweep it now, but only when the user asks to find new hardware: a sweep takes 10 seconds or more. If has_default_key is true for any agent, tell the user that agent is on the insecure default key and ask whether to change it.
Inputs: rescan.
Upgrade agent to the latest release, then restart it. A Pi runs install.sh --upgrade (re-downloads the release files and reinstalls dependencies); a Pico or ESP32 downloads the new files over WiFi, swaps them in and resets.
Inputs: agent (required).
Load a full config onto agent from a dict (the agent saves a backup first). Pass an empty dict {} to reset all settings on the agent keeping only its API key.
Inputs: agent (required), config (required).
Read agent's global application configuration, grouped: notifications (webhook + webhook_key), bridges (matter/homekit/homebridge callbacks), settings (docs_enabled, logs_enabled, log_days), sensors, and configured pins (gpios). The agent block (platform, os, ip, cpu_temperature, version) is computed live on every read and is not stored.
Inputs: agent (required).
Update agent's global configuration dynamically. These are the ungrouped (root) field names; the agent routes each into its group (webhook_url -> notifications.webhook, webhook_key -> notifications.webhook_key, docs_enabled/logs_enabled/log_days -> settings), so a read afterwards shows them nested. log_days controls how long log entries are kept (0-30, clamped; 0 clears the log immediately and keeps only the last hour). docs_enabled is Pi-only. Changing api_key changes the agent's authentication key immediately, and also updates the local agents-config.json file to match automatically.
Inputs: agent (required), name, api_key, log_days, +4 more.
Configure a GPIO pin on agent by number. type: input/output/vcc/gnd/remove. init: 0/1/last. pullup: up/down/none (input only). max: max pulse duration in seconds (output only). reversed: active-low logic (input/output only). watched: trigger webhook on state change (logged on the agent if no notifications.webhook is configured).
Inputs: gpio (required), agent (required), max, init, +5 more.
Read a GPIO pin value on agent by number or name, or 'all' to read all pins.
Inputs: agent (required), name_or_gpio (required).
Scan all hardware GPIO pins on agent and return each pin's level (the physical state), type, pull resistor and name; a reversed pin also reports value (its logical state) and reversed. Pins: BCM 2-27 on a Raspberry Pi, GP0-GP28 (minus the WiFi-reserved GP23/24/25/29) on a Pico, and every usable pin of the chip on an ESP32 (flash, PSRAM and USB pins are left out).
Inputs: agent (required).
List the GPIO pins that are currently being actively watched (the ones emitting hardware interrupts/webhooks).
Inputs: agent (required).
Write a value to a GPIO pin on agent ('0', '1', 'on', 'off', or 'toggle'). Optional duration in seconds, after which the pin reverts to its previous state. If the pin has a configured 'max' pulse duration, the effective duration is clamped to it - and if no duration is given but 'max' is set, 'max' is used as the duration automatically.
Inputs: agent (required), value (required), name_or_gpio (required), duration.
List the files in agent's scripts/ folder (the folder sensors run from): scripts ([{name, size, modified}]) and write: "enabled", "default_key" (writes are refused until the agent's api_key is changed from the default) or "locked" (a write.lock file there blocks every write).
Inputs: agent (required).
Read one file from agent's scripts/ folder. Returns {name, content}.
Inputs: name (required), agent (required).
Run a file from agent's scripts/ folder and return {name, exit_code, output}. On a Raspberry Pi a .py runs with the agent's Python and anything else with sh; output is its stdout (first 2 KB) and a run over 15 s is killed. On a Pico or ESP32 the file is exec'd in-process: output is what its read(*args) returns, or its result, and exit_code is 1 if it raised. args are letters and digits only.
Inputs: name (required), agent (required), args.
Create or overwrite a file in agent's scripts/ folder with content, or delete it with remove=true. name is a bare filename of up to 32 characters (letters, digits, . _ -, no leading dot or dash, no paths). Refused while the agent still has the default api_key, and once a write.lock file is in the folder. Writing write.lock (any content) locks every script write, and this tool can then no longer change or remove it. The lock does not stop runs: a script run with mcp_script_run that deletes files can remove write.lock, as can a shell (Pi) or USB (Pico, ESP32).
Inputs: name (required), agent (required), remove, content.
Configure a named sensor on agent. A sensor runs a script and its output is the reading. script is " [args...]": a bare filename in the agent's scripts/ folder (no paths - that folder is the only allowed location), with letters/digits-only arguments. On a Raspberry Pi it is a shell script run with sh; on a Pico or ESP32 a .py file the agent execs in-process. Pass remove=true to delete the sensor.
Inputs: name (required), agent (required), remove, script.
Read sensors on agent. With no name, reads every configured sensor and returns them merged into one JSON object; with a name, reads just that sensor. Every reading is nested under its sensor's own name: a script emitting a JSON object with several fields nests whole, one emitting a single-field object contributes just that field's value, and any other output is wrapped the same way.
Inputs: agent (required), name.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
Most tools map cleanly to a resource+action (script, gpio, sensor, config, agent), but there are a few soft overlaps: mcp_gpio_scan versus mcp_gpio_read with 'all', and mcp_config_write versus mcp_config_load both mutate configuration. Descriptions do distinguish them (scan includes pin metadata/type/pull/reversed, load replaces whole config with a backup), so an agent can resolve the boundary, but the pairs are close enough to occasionally misselect.
Every tool follows the same mcp_<resource>_<verb> snake_case pattern: script_list/read/write/run, gpio_scan/read/write/config/watched, sensor_config/read, config_read/write/load, agent_restart/upgrade/logs. No camelCase or verb-style deviations anywhere.
18 tools is on the upper end but the server genuinely spans several sub-domains (scripts, GPIO, sensors, global config, agent lifecycle), and each tool covers a distinct operation. It's slightly heavy but no tool looks superfluous.
Coverage is strong: scripts have list/read/write/delete/run, GPIO has scan/read/write/config/watched with removal via config, sensors have config/read with delete, config has read/write/load/reset, and agent has list/restart/upgrade/logs. The notable gap is agent management — there is no tool to add or remove an agent entry, even though the server manages an agents-config.json.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
