mcp-for-arduino
MCP server that lets AI clients do real Arduino work locally via arduino-cli.
Board discovery & info: list connected boards, search all supported boards, view FQBN details, run health checks (
board-list,board-listall,board-details,doctor)Sketch management: scaffold, validate layout, archive, preprocess source (
sketch-new,sketch-validate,sketch-archive,preprocess)Compile & flash: verify sketches without hardware, upload firmware, upload then monitor serial output, export binaries, burn bootloaders (
compile,upload,upload-and-monitor,export-binary,burn-bootloader)Serial monitoring: take non-blocking serial snapshots for debugging (
monitor-snapshot)Platform/core management: search, install, list, upgrade board cores (
core-search,core-install,core-list,core-upgrade)Library management: search, install, list, upgrade libraries, browse examples, check dependencies (
lib-search,lib-install,lib-list,lib-upgrade,lib-examples,lib-deps)Update awareness: show outdated cores/libraries (
outdated)Sketch profiles: save default port/FQBN per sketch to simplify later commands (
board-attach)Prompts & resources: new-sketch, fix-compile-error, migrate-board, optimize-sram, wiring-review, plus Arduino config/board/library/cheatsheet resources
Provides Arduino development capabilities through arduino-cli, including board detection, sketch compilation and upload, core/library management, sketch scaffolding/validation/archiving, serial monitoring, bootloader burning, and firmware export.
Supports Espressif ESP32 Arduino platform work by allowing installation and management of the esp32:esp32 core from Espressif's package index, alongside compiling, uploading, and serial monitoring for ESP32 boards.
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-for-arduino Upload my sketch to the connected Uno and show its serial output"
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.
mcp-for-arduino
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.
Super-easy setup (recommended)
No Node.js, no manual config. Pick your download from the latest release:
Windows:
mcp-for-arduino-windows-x64.zip→ unzip, double-clickmcp-for-arduino.exe.Mac Apple Silicon (M1/M2/M3/M4):
mcp-for-arduino-macos-arm64.zip→ unzip, double-clickInstall.command.Mac Intel:
mcp-for-arduino-macos-x64.zip→ unzip, double-clickInstall.command. (Not sure which Mac? Logo → About This Mac → Chip. No Terminal typing needed — macOS opens Terminal itself. If it says "unidentified developer": right-clickInstall.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-listfinds 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
Node.js 20+
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 supportmacOS:
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.ps1Connect 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.shTools (26)
Tool | What it does |
| Detect connected boards (port + FQBN). Start here. |
| All supported boards + FQBNs, filterable |
| Required core, options, programmer for an FQBN |
| Save default port/FQBN into a sketch profile (sketch.yaml) |
| Verify a sketch (no hardware needed). Returns flash/RAM usage or errors |
| Flash a sketch to |
| Flash, then instantly show the board's serial output — new code to visible result in one call |
| Health check: CLI, cores, libraries, boards, pending updates |
| Compile + export firmware files (.hex/.bin/.elf) to a folder |
| Print preprocessed sketch source (debug macros/conditional compiles) |
| Burn bootloader via external programmer (needs extra hardware) |
| Board platforms, e.g. |
| Library Manager |
| Bundled examples for libraries (starter code for sensors/modules) |
| Dependency status of a library |
| Cores + libraries with upgrades available |
| Scaffold, layout-check ( |
| Non-blocking serial read ( |
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
board-list→ port + FQBN (orboard-listall unoto look it up)board-attach→ save them to the sketch once, skip passing them afterwardssketch-validate→ fix<name>/<name>.inolayout mismatchescompile→ iterate until ✅upload-and-monitor→ flash + instantly see serial output (orupload, thenmonitor-snapshot)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 setARDUINO_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
.inonames 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 toolsboard-attachAIdempotent
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-bootloaderADestructive
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.
compileARead-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-installAIdempotent
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-searchC
Search available cores in Boards Manager (e.g. 'esp32', 'samd').
Inputs: query (required).
core-upgradeAIdempotent
Upgrade installed cores. Omit coreId to upgrade all.
Inputs: coreId.
doctorARead-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-binaryAIdempotent
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-depsARead-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-examplesARead-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-installBIdempotent
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-searchB
Search the Arduino Library Manager (e.g. 'Servo', 'DHT sensor', 'WiFi').
Inputs: query (required).
lib-upgradeAIdempotent
Upgrade libraries. Omit name to upgrade all.
Inputs: name.
monitor-snapshotARead-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.
outdatedARead-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.
preprocessARead-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-archiveBIdempotent
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-validateARead-onlyIdempotent
Check a sketch folder layout (/.ino) and list its files. Run before compile to catch layout mistakes.
Inputs: sketchPath (required).
uploadADestructiveIdempotent
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-monitorADestructiveIdempotent
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Deploy and manage Jade Hosting projects from AI clients. Jade account and OAuth required.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Arduino development through arduino-cli, allowing sketch management, code compilation and uploading, library and board operations, serial monitoring, and AI-powered circuit diagram generation using WireViz.10MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Arduino boards for compiling, uploading sketches, and serial communication.6MIT
- 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-