Skip to main content
Glama
Arduino Bridge MCP

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.

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

uv

any recent release

Arduino CLI

>=1.1.1,<2

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 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:

$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. 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:

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:

  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:

$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:

    .\.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:

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.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 for the design constraints that changes must preserve, and SECURITY.md for the threat model.

License

MIT

Available Tools

21 tools
cancel_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_managerA
Destructive

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_sketchA
Destructive

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_detailsB
Read-onlyIdempotent

Get board configuration options for an installed FQBN.

Inputs: fqbn (required). Returns: ok, data, error, status, +3 more

get_build_statusB
Read-onlyIdempotent

Read build state, diagnostics, memory usage, and successful artifact information.

Inputs: build_id (required). Returns: ok, data, error, status, +3 more

get_cli_versionB
Read-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_environmentB
Read-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_sketchA
Read-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_packageB
Destructive

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_boardsA
Read-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_coresA
Read-onlyIdempotent

List installed board cores with their installed and latest versions.

Inputs: no named parameters. Returns: ok, data, error, status, +3 more

list_librariesA
Read-onlyIdempotent

List installed Arduino libraries and versions.

Inputs: no named parameters. Returns: ok, data, error, status, +3 more

list_sketchesB
Read-onlyIdempotent

List sketches in the Arduino sketchbook, the same set Arduino IDE shows.

Inputs: include_paths. Returns: ok, data, error, status, +3 more

monitor_serialC
Destructive

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_boardsA
Read-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_coresB
Read-onlyIdempotent

Search configured Boards Manager indexes for cores and versions.

Inputs: query (required). Returns: ok, data, error, status, +3 more

search_librariesB
Read-onlyIdempotent

Search Library Manager for libraries and versions.

Inputs: query (required). Returns: ok, data, error, status, +3 more

upload_sketchB
Destructive

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_fileB
Destructive

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

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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).

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers