Arduino Bridge MCP
# Arduino Bridge MCP
A local stdio MCP server for the official Arduino toolchain on Windows. An agent
can discover boards and dependencies, edit saved sketches, compile for a board,
upload an approved build, and collect serial output.
Works with Claude Code, VS Code Copilot, Cursor, Codex, and GitHub Copilot CLI.
<img width="1672" height="941" alt="Arduino Bridge MCP_ AI-Powered Hardware Control" src="https://github.com/user-attachments/assets/4d46fded-1326-48e7-84b1-0f47dbfe6b45" />
## Why this exists
An agent with shell access can already run `arduino-cli`. This bridge adds the
parts that are easy to get wrong:
- **Board and dependency discovery** that reports what is actually installed,
including the missing Boards Manager index that hides every ESP8266 and ESP32
core.
- **Hash-checked file edits**, so an agent cannot silently overwrite a sketch you
changed in the IDE.
- **Approval-gated uploads.** A plan is approved in your own terminal, then the
port identity and firmware digest are re-verified before flashing.
- **Retained build artifacts** you can upload manually or inspect after the
server stops.
## Requirements
| Component | Version |
| --- | --- |
| Windows | 10 or 11 |
| Python | 3.11 or later |
| [uv](https://docs.astral.sh/uv/getting-started/installation/) | any recent release |
| [Arduino CLI](https://docs.arduino.cc/arduino-cli/installation) | `>=1.1.1,<2` |
The CLI bundled with Arduino IDE 2.x works; you do not need a separate install.
## Install
~~~powershell
git clone https://github.com/Syeed-MD-Talha/Arduino-Bridge-MCP.git
cd arduino-bridge-mcp
uv sync --locked
.\.venv\Scripts\arduino-bridge.exe doctor
~~~
`doctor` prints the detected IDE, CLI, sketchbook, and index configuration. It
exits with code 1 when the CLI or its configuration cannot be used. Use
`doctor --json --redact-paths` for a structured report suitable for sharing.
## Connect a host
Generate a config snippet for your client, then merge the `arduino-bridge` entry
into your existing config:
~~~powershell
$bridge = (Resolve-Path .\.venv\Scripts\arduino-bridge.exe).Path
& $bridge clients generate --client copilot --workspace .
~~~
Replace `copilot` with a name from the table below. The generator prints to
stdout and uses normal CLI discovery unless you pass `--arduino-cli` with an
absolute path. `--workspace` is the directory the sketch tools may touch.
| Client | `--client` | Config destination |
| --- | --- | --- |
| Claude Code | `claude` | Project-root `.mcp.json` |
| VS Code Copilot | `copilot` or `vscode` | Workspace `.vscode/mcp.json` |
| Cursor | `cursor` | Project `.cursor/mcp.json` or user `~/.cursor/mcp.json` |
| Codex | `codex` | Merge the TOML into your Codex `config.toml` |
| GitHub Copilot CLI | `copilot-cli` | User `~/.copilot/mcp-config.json` |
A hand-editable template lives at
[`examples/mcp.json.example`](examples/mcp.json.example). After connecting, ask
the client to call `get_cli_version` to confirm the server responds.
## Enable uploads, serial, and installs
These are off by default. Add them to the **server environment** in your client
config and restart the host:
| Setting | Capability |
| --- | --- |
| `ARDUINO_BRIDGE_ENABLE_UPLOAD=1` | Prepare and execute locally approved serial uploads |
| `ARDUINO_BRIDGE_ENABLE_SERIAL=1` | Open a serial monitor and optionally send text |
| `ARDUINO_BRIDGE_ENABLE_INSTALL=1` | Install indexed cores and libraries, and add Boards Manager index URLs |
## Quick start: ESP8266 and an OLED
Vendor cores are not in the bundled Arduino index, so add the index first:
~~~text
configure_board_manager("https://arduino.esp8266.com/stable/package_esp8266com_index.json")
install_package("core", "esp8266:esp8266", "3.1.2")
install_package("library", "Adafruit SSD1306", "2.5.17")
install_package("library", "Adafruit GFX Library", "1.13.0")
~~~
Then compile and upload one of the [examples](examples/README.md):
~~~text
compile_sketch("examples/I2cScan", "esp8266:esp8266:nodemcuv2")
get_build_status("<build_id>")
prepare_upload("<build_id>", "COM3")
~~~
Approve the plan in your own terminal, then call `upload_sketch`:
~~~powershell
.\.venv\Scripts\arduino-bridge.exe approve-upload '<approval_file from prepare_upload>'
~~~
## CLI discovery
The bridge checks these sources in order:
1. `ARDUINO_BRIDGE_CLI_PATH` in the server process environment.
2. `cli_path` in `%LOCALAPPDATA%\ArduinoBridgeMCP\settings.json`.
3. `arduino-cli.exe` on absolute `PATH` entries.
4. A bounded scan of detected Arduino IDE 2.x installation directories.
For an explicit executable path, use an absolute local path to an official CLI:
~~~powershell
$env:ARDUINO_BRIDGE_CLI_PATH = 'C:\Tools\Arduino CLI\arduino-cli.exe'
.\.venv\Scripts\arduino-bridge.exe doctor
~~~
To save the path for future launches, use the settings file with a value such
as `{"cli_path": "C:/Tools/Arduino CLI/arduino-cli.exe"}`. A bad explicit
selection returns an actionable error so you can correct the intended path.
The accepted stable Arduino CLI range is `>=1.1.1,<2`. Doctor reports the
effective directories and configuration source. Set `ARDUINO_BRIDGE_CONFIG_FILE`
to an absolute local Arduino CLI configuration file to select it explicitly.
The bridge also honors `ARDUINO_CONFIG_FILE`. With an IDE-bundled CLI, the bridge
uses the standard `~/.arduinoIDE/arduino-cli.yaml` when present. In other cases
the selected CLI resolves its default configuration.
## Tools
| Tool | Result |
| --- | --- |
| `get_cli_version` | Version, discovery source, and CLI capability flags |
| `get_environment` | IDE detection, CLI status, and effective directory and package-index configuration |
| `list_boards` | Connected boards and their serial ports, from `arduino-cli board list` |
| `list_cores` | Installed board cores with installed and latest versions |
| `list_sketches` | Saved sketches in the selected sketchbook, including category folders and legacy `.pde` sketches |
| `get_sketch`, `create_sketch`, `write_sketch_file` | Inspect, create, and edit saved sketch files within the configured workspace |
| `search_boards`, `get_board_details` | Find installed board definitions and supported FQBN options |
| `search_cores`, `list_libraries`, `search_libraries` | Inspect available cores and installed or indexed libraries |
| `configure_board_manager` | Add a third-party Boards Manager index URL so vendor cores can be found |
| `install_package` | Install a version-pinned indexed core or library |
| `compile_sketch`, `get_build_status`, `cancel_build` | Queue a saved-sketch build, inspect diagnostics and artifacts, or cancel it |
| `prepare_upload`, `upload_sketch` | Prepare and execute a one-time, locally approved serial upload |
| `monitor_serial` | Capture serial output for a bounded time and optionally send text |
`get_cli_version`, `get_environment`, and `list_sketches` hide paths unless you
pass `{"include_paths": true}`. Tool results include `ok`, `status`, `data`,
`error`, `warnings`, `next_actions`, and `request_id`. Tool execution failures
also set MCP's `isError`. For example, `CLI_NOT_FOUND` means the server is
connected and needs a CLI installation or explicit path.
## Agent workflow
1. Set `ARDUINO_BRIDGE_WORKSPACE` in the MCP server environment, or generate the
config with `--workspace`. Paths passed to sketch tools are relative to that
directory. Use `.` when the workspace itself is a sketch folder.
Pass `location="sketchbook"` to `create_sketch` to create the sketch in the
Arduino sketchbook instead, so it appears in Arduino IDE.
2. Call `get_sketch` with a sketch-relative file name to get its contents and
SHA-256. Pass that hash as `expected_sha256` when replacing the file.
Leave it unset to create a new file. Save pending IDE edits before working
on the same sketch through the bridge.
3. Call `compile_sketch` with the sketch path and an explicit FQBN such as
`arduino:avr:uno`. Poll `get_build_status` until the build finishes. Failed
builds return diagnostics, and successful builds return memory usage when
available plus the names and digest of the retained firmware files.
Builds use a copy of the saved project, with `sketch.yaml` omitted to keep
board selection explicit and use the configured installed toolchain.
Build IDs are scoped to the running server. The bridge keeps up to six
builds and removes its temporary build files when it exits. Firmware
artifacts are retained outside the temporary directory, and
`artifact_directory` reports where they are, so a build can be uploaded
manually or inspected after the server stops.
4. For an upload, call `list_boards`, select the correct serial port, and call
`prepare_upload` with the successful build ID and port. Review and approve
the plan in your own PowerShell terminal:
~~~powershell
.\.venv\Scripts\arduino-bridge.exe approve-upload '<approval_file from prepare_upload>'
~~~
The plan is valid for five minutes. Type the displayed port when prompted.
The agent can then call `upload_sketch` with the plan's upload ID. The bridge
rechecks the port identity and artifact digest and consumes the approval
before starting the uploader. Some USB adapters supply no stable hardware
ID. Confirm the physical device at the displayed port in that case.
5. Call `monitor_serial` with the port and sketch baud rate. Pass `send` to
transmit UTF-8 text, including any required newline. Close the Arduino IDE
Serial Monitor first so the bridge can open the port. The capture window
includes CLI startup time, and opening a serial port can reset some boards.
Set these in the **server environment** and restart the MCP host to enable
optional operations:
| Setting | Capability |
| --- | --- |
| `ARDUINO_BRIDGE_ENABLE_UPLOAD=1` | Prepare and execute locally approved serial uploads |
| `ARDUINO_BRIDGE_ENABLE_SERIAL=1` | Open a serial monitor and optionally send text |
| `ARDUINO_BRIDGE_ENABLE_INSTALL=1` | Install indexed cores and libraries at explicit versions, and add Boards Manager index URLs |
Vendor cores such as ESP8266 and ESP32 are not in the bundled Arduino index.
Add the vendor index before searching for them:
~~~text
configure_board_manager("https://arduino.esp8266.com/stable/package_esp8266com_index.json")
configure_board_manager("https://espressif.github.io/arduino-esp32/package_esp32_index.json")
~~~
`get_environment` warns when no third-party index is configured, and an empty
`search_cores` or `search_libraries` result explains the same fix in
`next_actions` instead of returning a silent empty list. Index URLs are
reported with any embedded credentials and query tokens removed.
Install libraries and their dependencies explicitly by version. The install
tools skip replacing existing versions and require Arduino CLI's unsafe
installation settings to be off. Use trusted executables, indexes, and board
packages. Arduino CLI can download indexes during initialization, and board
packages can run commands during builds. The MCP host can forward source,
diagnostics, and serial text to its model provider. Keep any credentials out
of that material.
The bridge works with saved files and Arduino CLI. Live IDE editor buffers,
the IDE's active board selection, graphical debugging, bootloader burning,
and network uploads are outside the current tool surface.
## Development and verification
~~~powershell
uv sync --locked --extra dev
uv run --no-sync ruff check src tests
uv run --no-sync ruff format --check src tests
uv run --no-sync mypy
uv run --no-sync pytest
pwsh -File .\tests\inspector-smoke.ps1
~~~
The Python tests cover the subprocess runner, both MCP protocol eras,
source revision checks, and simulated upload approval and target changes.
The Inspector smoke test checks workflow discovery and calls the inventory
tools through the installed server. Use Node.js 24.22.1 or a newer supported
version and pass the Arduino CLI path with `-ArduinoCli` if it is unavailable
on `PATH` or in `ARDUINO_BRIDGE_CLI_PATH`. Set `ARDUINO_BRIDGE_TEST_CLI` to a CLI
with the Arduino AVR core installed to run the real compile and diagnostic
smoke test through MCP.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the design constraints that changes
must preserve, and [SECURITY.md](SECURITY.md) for the threat model.
## License
[MIT](LICENSE)
TDQS
Scored across 21 tools
Most tools target distinct resources and actions (sketch CRUD, build lifecycle, upload, serial). A few pairs are subtle — list_cores vs search_cores, and especially list_boards vs search_boards vs get_board_details — and get_cli_version overlaps with get_environment, but the descriptions clarify the installed-vs-indexed and version-vs-config distinctions.
Every tool follows a consistent snake_case verb_noun pattern: list_*, get_*, create_*, write_*, search_*, configure_*, install_*, compile_*, cancel_*, prepare_*, upload_*, monitor_*. The build/upload lifecycle names align predictably (get_build_status, cancel_build, prepare_upload, upload_sketch).
21 tools is on the heavy side for a single server, but the breadth of the Arduino domain (cores, libraries, boards, sketches, build, upload, serial) justifies the surface and each tool covers a real operation. It sits near the upper reasonable bound rather than being padded.
The surface covers discovery, environment config, sketch read/write/create, package search/install, full build lifecycle, upload planning/execution, and serial monitoring. Minor gaps remain: no delete for sketches or files and no uninstall_package, so lifecycle removal operations are absent.