Skip to main content
Glama
mcp-for-arduino

mcp-for-arduino

by blame-me

mcp-for-arduino

CI Release License

MCP server that lets AI clients (Claude Desktop, VS Code, Cursor, OpenCode) do real Arduino work: compile sketches, flash boards, manage platforms/libraries, scaffold sketches, and read serial output. Built on TypeScript + MCP SDK v2, wrapping arduino-cli (the engine inside Arduino IDE 2.x) over stdio.

No Node.js, no manual config. Pick your download from the latest release:

  • Windows: mcp-for-arduino-windows-x64.zip → unzip, double-click mcp-for-arduino.exe.

  • Mac Apple Silicon (M1/M2/M3/M4): mcp-for-arduino-macos-arm64.zip → unzip, double-click Install.command.

  • Mac Intel: mcp-for-arduino-macos-x64.zip → unzip, double-click Install.command. (Not sure which Mac? Logo → About This Mac → Chip. No Terminal typing needed — macOS opens Terminal itself. If it says "unidentified developer": right-click Install.command → Open → Open, once.)

The app sets itself up: fetches arduino-cli, installs Uno/Mega/Nano board support, and registers itself in every AI client (Claude Desktop, OpenCode, VS Code, Cursor, Claude Code, Gemini CLI, Windsurf — each existing config is backed up first, your other servers are kept). Then restart your AI client and ask: "list my Arduino boards".

Setup is idempotent — run it again any time to repair or update things.

Mac notes: board ports look like /dev/cu.usbmodemXXXX — board-list finds them. Clone boards may need the vendor USB driver (WCH CH340 / Silicon Labs CP210x) before they appear.

Related MCP server: Arduino MCP Server (Simple)

Manual setup (developers)

Prerequisites

  1. Node.js 20+

  2. arduino-cli (verified with v1.5.1):

    # Windows
    winget install --exact --id ArduinoSA.CLI
    arduino-cli config init
    arduino-cli core update-index
    arduino-cli core install arduino:avr   # Uno / Mega / Nano support

    macOS: brew install arduino-cli · Linux: see arduino-cli install docs.

Build & run

cd path\to\arduino-mcp   # wherever you cloned / unzipped the repo
npm install
npm run build     # tsc -> build/
npm run dev       # dev: tsx src/index.ts (stdio)

To rebuild the standalone exe yourself:

powershell -ExecutionPolicy Bypass -File scripts/build.ps1
# -> mcp-for-arduino.exe + mcp-for-arduino-windows-x64.zip at the root
#    (needs Node 20+ with SEA support to build,
#     but the resulting exe runs anywhere with no Node installed)

Smoke-test the exe (no hardware needed):

powershell -ExecutionPolicy Bypass -File scripts/test.ps1

Connect a client

All clients spawn the server locally over stdio. Easiest: point at the exe (this is exactly what the built-in setup writes for Claude Desktop):

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{ "mcpServers": { "arduino": { "command": "C:\\path\\to\\mcp-for-arduino.exe" } } }

VS Code / Cursor (.vscode/mcp.json or ~/.cursor/mcp.json):

{ "servers": { "arduino": { "type": "stdio", "command": "C:\\path\\to\\mcp-for-arduino.exe" } } }

OpenCode (opencode.json):

{ "mcp": { "arduino": { "type": "local", "command": ["C:\\path\\to\\mcp-for-arduino.exe"] } } }

Optional env: ARDUINO_CLI_PATH to point at a non-PATH arduino-cli binary (the installer sets this to its portable copy automatically). Developers running from source can use node + build/index.js instead of the exe.

Folder layout (dev checkout)

mcp-for-arduino.exe   <- Windows server. Double-click it to install/update everything.
mcp-for-arduino-macos(-arm64|-x64).zip <- Mac downloads (built by scripts/build-mac.ps1)
arduino-mcp/          <- everything else (source, scripts, this readme)
  src/                <- TypeScript source (server + built-in setup)
  scripts/            <- build.ps1, build-mac.ps1, test.ps1, inject-sea.mjs, sea-config.json, mac-install.sh

Tools (26)

Tool

What it does

board-list

Detect connected boards (port + FQBN). Start here.

board-listall [query]

All supported boards + FQBNs, filterable

board-details --fqbn

Required core, options, programmer for an FQBN

board-attach

Save default port/FQBN into a sketch profile (sketch.yaml)

compile

Verify a sketch (no hardware needed). Returns flash/RAM usage or errors

upload

Flash a sketch to --port. Close Serial Monitor first (port lock)

upload-and-monitor

Flash, then instantly show the board's serial output — new code to visible result in one call

doctor

Health check: CLI, cores, libraries, boards, pending updates

export-binary

Compile + export firmware files (.hex/.bin/.elf) to a folder

preprocess

Print preprocessed sketch source (debug macros/conditional compiles)

burn-bootloader

Burn bootloader via external programmer (needs extra hardware)

core-list / core-search / core-install / core-upgrade

Board platforms, e.g. arduino:avr, esp32:esp32

lib-list / lib-search / lib-install / lib-upgrade

Library Manager

lib-examples [name]

Bundled examples for libraries (starter code for sensors/modules)

lib-deps

Dependency status of a library

outdated

Cores + libraries with upgrades available

sketch-new / sketch-validate / sketch-archive

Scaffold, layout-check (<name>/<name>.ino), zip

monitor-snapshot

Non-blocking serial read (--port --baudrate --timeoutMs, max 15s)

Tip: run board-attach once per sketch — afterwards compile, upload, upload-and-monitor, export-binary and preprocess no longer need fqbn/port passed every time.

Resources: arduino://config, arduino://boards, arduino://libraries, arduino://cores, arduino://cheatsheet, plus sketch://{name} (read-only source of sketches in your Arduino folder). Prompts: new-sketch, fix-compile-error, migrate-board, optimize-sram, wiring-review.

The exe also checks GitHub releases for updates every time you run setup.

Typical agent workflow

  1. board-list → port + FQBN (or board-listall uno to look it up)

  2. board-attach → save them to the sketch once, skip passing them afterwards

  3. sketch-validate → fix <name>/<name>.ino layout mismatches

  4. compile → iterate until ✅

  5. upload-and-monitor → flash + instantly see serial output (or upload, then monitor-snapshot)

  6. doctor → run whenever anything behaves oddly

Common FQBNs: Uno arduino:avr:uno, Mega arduino:avr:mega, Nano arduino:avr:nano (old bootloader: --boardOptions cpu=atmega328old), ESP32 esp32:esp32:esp32 (requires --additionalUrls ["https://dl.espressif.com/dl/package_esp32_index.json"]).

Troubleshooting

  • arduino-cli not found → install it (above) or set ARDUINO_CLI_PATH.

  • port busy / access denied → close IDE Serial Monitor; only one holder per COM port.

  • No boards detected → USB cable (charge-only cables fool everyone), drivers (CH340/CP210x for clones), Device Manager COM check.

  • Compile layout error → folder and .ino names must match exactly.

  • First ESP32 compile is slow (5–10 min toolchain download); timeouts are set generously (up to 10 min for core install).

Available Tools

26 tools
board-attachA
Idempotent

Save default port + FQBN (+ optional programmer) into a sketch's profile (sketch.yaml), so later compile/upload calls can omit them. With no sketchPath, shows current defaults.

Inputs: fqbn, port, programmer, sketchPath.

board-detailsB

Show details for an FQBN: required core, board options, default programmer.

Inputs: fqbn (required).

board-listA

List connected Arduino boards (port, protocol, detected FQBN). Run this first to find the upload port and FQBN.

Inputs: no named parameters.

board-listallA

List all supported boards and their FQBNs. Optionally filter by name (e.g. 'uno', 'esp32', 'nano').

Inputs: query.

burn-bootloaderA
Destructive

Burn the bootloader onto a board using an EXTERNAL PROGRAMMER (e.g. USBasp, atmel_ice). Requires extra hardware — this is not a normal upload. Double-check fqbn + programmer before running.

Inputs: fqbn (required), programmer (required), port.

compileA
Read-onlyIdempotent

Compile an Arduino sketch for a board. Verifies code without needing hardware. Returns memory usage and errors.

Inputs: sketchPath (required), fqbn, verbose, libraries, +3 more.

core-installA
Idempotent

Install a board core, e.g. 'arduino:avr' (Uno) or 'esp32:esp32' (needs additional URL). Takes a while on first install.

Inputs: coreId (required), version, additionalUrls.

core-listA

List installed board platforms/cores (e.g. arduino:avr) with versions.

Inputs: no named parameters.

core-upgradeA
Idempotent

Upgrade installed cores. Omit coreId to upgrade all.

Inputs: coreId.

doctorA
Read-onlyIdempotent

Health check for the whole Arduino setup: CLI, cores, libraries, connected boards, pending updates. Run first when anything behaves oddly.

Inputs: no named parameters.

export-binaryA
Idempotent

Compile a sketch and export the firmware files (.hex/.bin/.elf) to a folder. Use for flashing with external tools, OTA updates, or archiving builds.

Inputs: sketchPath (required), fqbn, outputDir, boardOptions, +1 more.

lib-depsA
Read-onlyIdempotent

Check the dependency status of a library (what it needs, what's missing). Run before compile when a library install seems incomplete.

Inputs: name (required).

lib-examplesA
Read-onlyIdempotent

List the bundled examples for installed libraries. Omit name to list examples for all libraries. Great for finding starter code for a sensor/module.

Inputs: name.

lib-installB
Idempotent

Install a library from Library Manager, e.g. 'Servo' or 'DHT sensor library'.

Inputs: name (required), noDeps, version.

lib-listB

List installed Arduino libraries.

Inputs: fqbn.

lib-upgradeA
Idempotent

Upgrade libraries. Omit name to upgrade all.

Inputs: name.

monitor-snapshotA
Read-onlyIdempotent

Read serial output from a board for a few seconds (non-blocking snapshot). Use for Serial.println debugging. NOT a live stream — returns what arrived within timeoutMs.

Inputs: port, baudrate, timeoutMs, sketchPath.

outdatedA
Read-onlyIdempotent

Show installed cores and libraries that have upgrades available. Empty output means everything is current. Follow up with core-upgrade / lib-upgrade.

Inputs: no named parameters.

preprocessA
Read-onlyIdempotent

Print the preprocessed sketch source (macros expanded, headers resolved) instead of compiling. Useful for debugging #define / conditional-compile issues.

Inputs: sketchPath (required), fqbn, additionalUrls, buildProperties.

sketch-archiveB
Idempotent

Zip a sketch (optionally including build artifacts).

Inputs: sketchPath (required), output, includeBuildArtifacts.

sketch-newA

Create a new Arduino sketch (folder + .ino file with setup()/loop() boilerplate).

Inputs: path (required).

sketch-validateA
Read-onlyIdempotent

Check a sketch folder layout (/.ino) and list its files. Run before compile to catch layout mistakes.

Inputs: sketchPath (required).

uploadA
DestructiveIdempotent

Compile (if needed) and flash a sketch to a connected board. fqbn/port can be omitted if saved with board-attach. Close Serial Monitor first — it locks the port.

Inputs: sketchPath (required), fqbn, port, verify, +3 more.

upload-and-monitorA
DestructiveIdempotent

Flash a sketch and immediately show its serial output — one call from new code to visible result. Uploads, waits for the board to reboot, then captures a serial snapshot.

Inputs: sketchPath (required), fqbn, port, verify, +4 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 26 tools

    Disambiguation4/5

    Most tools target a distinct stage of the Arduino workflow, and descriptions clarify pairs like board-listall (supported boards) vs board-list (connected boards). A few pairs remain close enough to cause occasional misselection, especially compile vs export-binary and monitor-snapshot vs upload-and-monitor, but overall boundaries are clear.

    Naming Consistency4/5

    Names generally follow a predictable resource-action kebab-case pattern (core-install, lib-search, sketch-new, board-attach). However, exceptions like bare compile/upload, noun-style doctor/outdated, and the awkward board-listall vs board-list prevent a perfect score.

    Tool Count3/5

    26 tools is above the ideal range and the server splits the workflow into many narrow endpoints, such as export-binary and preprocess alongside compile. The breadth maps to the real Arduino CLI, so it feels heavy but not bloated.

    Completeness4/5

    The set covers board discovery, core/library management, sketch lifecycle, compile/upload, bootloader burning, and serial diagnostics, so the main development loop is well supported. Obvious gaps are core-uninstall/lib-uninstall and managing extra Boards Manager URLs, but agents can usually work around these.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers