Arduino Bridge MCP
Drives the official Arduino toolchain through arduino-cli: discovers connected boards and serial ports, lists installed cores and libraries, searches board definitions and FQBN options, adds third-party Boards Manager index URLs (e.g. ESP8266/ESP32 cores), installs version-pinned cores and libraries, and compiles saved sketches for a given board while reporting diagnostics, memory usage, and retained firmware artifacts. Uploads are approval-gated — a plan is approved locally in the user's terminal, then the port identity and firmware digest are re-verified before flashing — and serial output can be captured (and optionally text sent) from the board.
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., "@Arduino Bridge MCP compile my I2cScan sketch for the NodeMCU and check the build status"
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.
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.
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.
Related MCP server: arduino-mcp-server
Requirements
Component | Version |
Windows | 10 or 11 |
Python | 3.11 or later |
any recent release | |
|
The CLI bundled with Arduino IDE 2.x works; you do not need a separate install.
Install
git clone https://github.com/Syeed-MD-Talha/Arduino-Bridge-MCP.git
cd arduino-bridge-mcp
uv sync --locked
.\.venv\Scripts\arduino-bridge.exe doctordoctor 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:
$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 |
| Config destination |
Claude Code |
| Project-root |
VS Code Copilot |
| Workspace |
Cursor |
| Project |
Codex |
| Merge the TOML into your Codex |
GitHub Copilot CLI |
| User |
A hand-editable template lives at
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 |
| Prepare and execute locally approved serial uploads |
| Open a serial monitor and optionally send text |
| 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:
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:
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:
.\.venv\Scripts\arduino-bridge.exe approve-upload '<approval_file from prepare_upload>'CLI discovery
The bridge checks these sources in order:
ARDUINO_BRIDGE_CLI_PATHin the server process environment.cli_pathin%LOCALAPPDATA%\ArduinoBridgeMCP\settings.json.arduino-cli.exeon absolutePATHentries.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:
$env:ARDUINO_BRIDGE_CLI_PATH = 'C:\Tools\Arduino CLI\arduino-cli.exe'
.\.venv\Scripts\arduino-bridge.exe doctorTo 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 |
| Version, discovery source, and CLI capability flags |
| IDE detection, CLI status, and effective directory and package-index configuration |
| Connected boards and their serial ports, from |
| Installed board cores with installed and latest versions |
| Saved sketches in the selected sketchbook, including category folders and legacy |
| Inspect, create, and edit saved sketch files within the configured workspace |
| Find installed board definitions and supported FQBN options |
| Inspect available cores and installed or indexed libraries |
| Add a third-party Boards Manager index URL so vendor cores can be found |
| Install a version-pinned indexed core or library |
| Queue a saved-sketch build, inspect diagnostics and artifacts, or cancel it |
| Prepare and execute a one-time, locally approved serial upload |
| 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
Set
ARDUINO_BRIDGE_WORKSPACEin 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. Passlocation="sketchbook"tocreate_sketchto create the sketch in the Arduino sketchbook instead, so it appears in Arduino IDE.Call
get_sketchwith a sketch-relative file name to get its contents and SHA-256. Pass that hash asexpected_sha256when replacing the file. Leave it unset to create a new file. Save pending IDE edits before working on the same sketch through the bridge.Call
compile_sketchwith the sketch path and an explicit FQBN such asarduino:avr:uno. Pollget_build_statusuntil 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, withsketch.yamlomitted 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, andartifact_directoryreports where they are, so a build can be uploaded manually or inspected after the server stops.For an upload, call
list_boards, select the correct serial port, and callprepare_uploadwith the successful build ID and port. Review and approve the plan in your own PowerShell terminal:.\.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_sketchwith 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.Call
monitor_serialwith the port and sketch baud rate. Passsendto 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 |
| Prepare and execute locally approved serial uploads |
| Open a serial monitor and optionally send text |
| 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:
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
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.ps1The 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 for the design constraints that changes must preserve, and SECURITY.md for the threat model.
License
Available Tools
21 toolscancel_buildB
Cancel a queued or running build and release its toolchain slot.
Inputs: build_id (required). Returns: ok, data, error, status, +3 more
compile_sketchA
Queue a build of a saved sketch snapshot for this FQBN. Poll get_build_status with the build ID.
Inputs: fqbn (required), sketch (required). Returns: ok, data, error, status, +3 more
configure_board_managerADestructive
Add a third-party Boards Manager index URL so vendor cores can be searched and installed.
Required before ESP8266, ESP32, and most non-Arduino cores appear in search_cores. Requires server-owner opt-in.
Inputs: url (required). Returns: ok, data, error, status, +3 more
create_sketchADestructive
Create a new sketch folder and matching .ino file.
Use location="sketchbook" so the sketch appears in Arduino IDE; the default writes inside the configured workspace.
Inputs: sketch (required), content, location. Returns: ok, data, error, status, +3 more
get_board_detailsBRead-onlyIdempotent
Get board configuration options for an installed FQBN.
Inputs: fqbn (required). Returns: ok, data, error, status, +3 more
get_build_statusBRead-onlyIdempotent
Read build state, diagnostics, memory usage, and successful artifact information.
Inputs: build_id (required). Returns: ok, data, error, status, +3 more
get_cli_versionBRead-onlyIdempotent
Detect Arduino CLI and return its version, discovery source, and read-only capabilities.
Inputs: include_paths. Returns: ok, data, error, status, +3 more
get_environmentBRead-onlyIdempotent
Check Arduino IDE, CLI, and effective CLI configuration. Request paths only when needed.
Inputs: include_paths. Returns: ok, data, error, status, +3 more
get_sketchARead-onlyIdempotent
List files in a saved sketch. Specify a sketch-relative file to read its UTF-8 text and SHA-256.
Inputs: sketch (required), file. Returns: ok, data, error, status, +3 more
install_packageBDestructive
Install an indexed core or library at an explicit version. Requires server-owner opt-in.
Inputs: kind (required), name (required), version (required). Returns: ok, data, error, status, +3 more
list_boardsARead-onlyIdempotent
List connected boards and their serial ports, as reported by arduino-cli board list.
Inputs: no named parameters. Returns: ok, data, error, status, +3 more
list_coresARead-onlyIdempotent
List installed board cores with their installed and latest versions.
Inputs: no named parameters. Returns: ok, data, error, status, +3 more
list_librariesARead-onlyIdempotent
List installed Arduino libraries and versions.
Inputs: no named parameters. Returns: ok, data, error, status, +3 more
list_sketchesBRead-onlyIdempotent
List sketches in the Arduino sketchbook, the same set Arduino IDE shows.
Inputs: include_paths. Returns: ok, data, error, status, +3 more
monitor_serialCDestructive
Capture a bounded serial session. Optionally send UTF-8 text including any desired line ending.
Inputs: port (required), baud, send, seconds. Returns: ok, data, error, status, +3 more
prepare_uploadC
Create a five-minute plan for one successful build and serial port. Show approval_file to the user.
Inputs: port (required), build_id (required). Returns: ok, data, error, status, +3 more
search_boardsARead-onlyIdempotent
Find installed board definitions by name or FQBN, even without a board attached.
Inputs: query (required). Returns: ok, data, error, status, +3 more
search_coresBRead-onlyIdempotent
Search configured Boards Manager indexes for cores and versions.
Inputs: query (required). Returns: ok, data, error, status, +3 more
search_librariesBRead-onlyIdempotent
Search Library Manager for libraries and versions.
Inputs: query (required). Returns: ok, data, error, status, +3 more
upload_sketchBDestructive
Flash a one-time upload plan after local terminal approval and fresh target verification.
Inputs: upload_id (required). Returns: ok, data, error, status, +3 more
write_sketch_fileBDestructive
Create a new UTF-8 sketch file or replace an existing file with its SHA-256 from get_sketch.
Inputs: file (required), sketch (required), content (required), expected_sha256. Returns: ok, data, error, status, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Search, read, preview, create, update, rename, arrange and trash sketches in your Google Drive.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Arduino boards for compiling, uploading sketches, and serial communication.6MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to compile, upload, and monitor Arduino boards via natural language, with electrical safety checks and dependency management.21202 npm26MIT
- AlicenseAqualityDmaintenanceAutomates Arduino CLI workflows including dependency checks, compile/upload, serial monitoring, and safety preflight checks, all running locally on your machine.21202 npm3MIT
- FlicenseAqualityCmaintenanceA local stdio MCP server wrapping arduino-cli to let agents detect boards, manage cores/libraries, compile and upload sketches, and communicate over serial, enabling hardware control without shell gymnastics.17-