arduino-mcp-server
This server gives an AI assistant full control over Arduino hardware through natural language, wrapping arduino-cli as MCP tools.
Detect connected boards, serial ports, and infer FQBNs
Check, install, and configure Arduino CLI
Install board cores automatically
Compile sketches for target board FQBNs
Upload sketches to boards, optionally waiting for a device-ready serial signal
Open, read, write, expect, list, and close stateful serial monitor sessions
Capture one-shot serial snapshots
Run electrical safety preflights covering power, wiring, battery charge rate, battery polarity, and ESP32-family pin risks
Get detailed board metadata and pin/capability references
List and search board reference data
Trigger safe, guardrailed hardware workflows while allowing explicit risk overrides
Allows AI assistants to control Arduino hardware: detect boards, compile and upload sketches, monitor serial, and run safety checks.
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-mcp-server compile and upload Blink to Arduino Uno"
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-mcp-server
Give your AI assistant full control over Arduino — compile, upload, monitor serial, and verify wiring safety, all through natural language.
Part of the HardwareMCP ecosystem — open-source MCP servers that bridge AI to physical hardware.
What this does
AI assistants can control Jira, GitHub, and databases. They can't talk to a microcontroller — until now.
arduino-mcp-server wraps arduino-cli into an MCP server so your AI can:
Detect connected boards and ports automatically
Compile and upload sketches without touching the terminal
Monitor serial output with stateful sessions (open, read, expect, write, close)
Run electrical safety checks before sending commands to hardware
Manage dependencies — cores, libraries, and CLI installation
Related MCP server: Arduino MCP Server (Simple)
Quick Start
Install:
npm install -g arduino-mcp-serverAdd to Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"arduino": {
"command": "npx",
"args": ["-y", "arduino-mcp-server"],
"env": {
"ARDUINO_CLI_PATH": "arduino-cli",
"ARDUINO_SKETCH_ROOT": "/path/to/your/sketches"
}
}
}
}Requires arduino-cli on your PATH, or let the server install it for you.
What you can say
Bootstrap from scratch:
"Check if Arduino CLI is installed and set everything up for an Arduino Uno."
Compile and upload:
"Compile my Blink sketch and upload it to the Uno on COM6."
Serial monitoring:
"Open serial on COM6 at 115200 and wait until the device prints READY."
Safety-first workflows:
"Run a safety preflight for an Arduino Uno with 5V on pin 13 at 25mA before I send commands."
Tools
Tool | What it does |
| Check Arduino CLI installation and version |
| Guide through arduino-cli installation |
| Detect connected boards and infer FQBNs |
| List all connected Arduino boards |
| List available serial ports |
| Check/install board cores |
| Compile a sketch for a target board |
| Upload compiled sketch to a board |
| Upload and wait for device ready signal |
| Open a stateful serial session |
| Read buffered serial data |
| Wait for a pattern in serial output |
| Send data over serial |
| Close a serial session |
| List active serial sessions |
| Quick one-shot serial read |
| Electrical safety check before hardware ops |
| Get pin/capability details for a board |
| List all boards arduino-cli supports |
| Browse board pin reference |
| Search board reference by keyword |
Resources:
arduino://boards/reference— structured board pin/capability reference
Prompts:
arduino-cli-bootstrap-policy— policy for arduino-cli setup behaviorarduino-setup-assistant— guided Arduino environment setup
Safety preflight guardrails
safety_preflight (and the safetyContext passed to upload_sketch, upload_and_wait_ready, and serial_write) now also covers battery and ESP32-family pin footguns, driven by small, extensible data tables rather than hardcoded to any one board:
Battery charge-rate (C-rate) check — pass a battery object (capacityMah, chargeCurrentMa, chemistry) and the check computes chargeCurrentMa / batteryCapacityMah and flags it:
BATTERY_CRATE_UNSAFE(hard, blocking) above 1CBATTERY_CRATE_CAUTION(soft, non-blocking) above 0.5C
Generic small LiPo cells are commonly rated for roughly a 0.5–1C safe charge current, so the message spells out the math, e.g. "380mA into a 100mAh cell is a 3.8C rate — well above the ~0.5-1C safe range for typical small LiPo cells; verify your cell's actual rated charge current before proceeding." If chargeCurrentMa is omitted, it's inferred from a small board → onboard-charge-IC lookup table (currently seeded with Seeed XIAO ESP32S3, XIAO ESP32S3 Sense, and XIAO ESP32C3 — see data/battery-charge-ic-reference.json, easy to extend with more boards). These are approximate, manufacturer-published figures — verify against the live datasheet/wiki for your exact board revision before trusting them in a production workflow.
Battery polarity confirmation — when battery.connecting: true (or any battery field is set) but battery.polarityConfirmed isn't explicitly true, the preflight blocks with BATTERY_POLARITY_UNCONFIRMED and a reminder to never assume BAT+/BAT- from wire color. On Seeed XIAO boards it cites the official convention: the negative pad is closest to the USB-C port, positive is farthest from it.
ESP32-family pin safety (table-driven per board via data/board-reference.json):
SPI-flash pins (GPIO6-11 on classic ESP32 WROOM/WROVER modules) — hard error (
SPI_FLASH_PIN_USED); wiring these prevents boot.Boot-strapping pins (GPIO0/2/12/15 on classic ESP32) — caution; usable at runtime but risky if externally held during boot/reset (existing check).
Input-only pins with no internal pull resistor (GPIO34-39 on classic ESP32) — caution (
NO_INTERNAL_PULL_PIN); add an external pull-up/pull-down if using them as buttons/switches.Seeed XIAO ESP32S3 — modeled with its 11 usable GPIO (D0-D10), default I2C on D4/D5, and an informational note surfaced whenever D6/D7 are wired: they're hardware UART1 TX/RX by default, but enabling "USB CDC on Boot" frees them as plain GPIO.
Board data for all of the above lives in JSON, keyed by board id/FQBN, so more boards can be added without touching guardrail logic.
Configuration
Variable | Default | Description |
|
| Path to arduino-cli binary |
| (none) | Restrict sketch paths to this directory |
Development
git clone https://github.com/hardware-mcp/arduino-mcp-server
cd arduino-mcp-server
npm install
npm run typecheck
npm test
npm run build
npm run devPart of HardwareMCP
This server is part of the HardwareMCP ecosystem — a collection of MCP servers that give AI assistants real control over physical hardware.
License
MIT — see LICENSE.
Support
Available Tools
21 toolsarduino_cli_doctorArduino CLI DoctorARead-only
Check whether arduino-cli is available and return OS-specific installation instructions if missing.
Inputs: no named parameters. Returns: ok, status, command, data, +9 more
compile_sketchCompile SketchADestructiveIdempotent
Compile an Arduino sketch with a specific board FQBN.
Inputs: sketchPath (required), fqbn (required), exportBinaries, clean, +3 more. Returns: ok, status, command, data, +9 more
detect_hardwareDetect HardwareBRead-only
Detect connected Arduino-compatible hardware, infer board/FQBN candidates, and generate next compile/upload commands.
Inputs: port, includeBoardDetails. Returns: ok, status, command, data, +9 more
ensure_core_installedEnsure Core InstalledADestructiveIdempotent
Ensure the Arduino core required by a board FQBN is installed. Can auto-install via arduino-cli core install.
Inputs: fqbn, coreId, autoInstall. Returns: ok, status, command, data, +9 more
get_board_detailsGet Board DetailsARead-only
Get detailed board metadata from arduino-cli for a specific FQBN.
Inputs: fqbn (required). Returns: ok, status, command, data, +9 more
install_arduino_cliInstall Arduino CLIADestructiveIdempotent
Attempt to install arduino-cli for the current OS using available package managers, then verify and configure CLI path.
Inputs: method, setCliPathInProcess. Returns: ok, status, command, data, +9 more
list_board_referenceList Board ReferenceARead-only
List local board reference entries with pin/spec metadata.
Inputs: no named parameters. Returns: ok, status, command, data, +9 more
list_connected_boardsList Connected BoardsARead-only
List connected boards and serial ports detected by arduino-cli.
Inputs: no named parameters. Returns: ok, status, command, data, +9 more
list_serial_portsList Serial PortsARead-only
List serial ports and any detected board metadata using arduino-cli. Works on Windows/macOS/Linux.
Inputs: no named parameters. Returns: ok, status, command, data, +9 more
list_supported_boardsList Supported BoardsARead-only
List supported/installable boards from the local arduino-cli index.
Inputs: search. Returns: ok, status, command, data, +9 more
read_serial_snapshotRead Serial SnapshotBRead-only
Capture serial output for a bounded duration from a given port.
Inputs: port (required), baudRate, durationMs. Returns: ok, status, command, data, +9 more
safety_preflightSafety PreflightARead-only
Run electrical preflight checks (voltage/current/pin risks) before upload or serial write operations.
Inputs: board, fqbn, port, wiring, +1 more. Returns: ok, status, command, data, +9 more
search_board_referenceSearch Board ReferenceARead-only
Search local board reference by board name, alias, id, or FQBN.
Inputs: query (required). Returns: ok, status, command, data, +9 more
serial_close_sessionSerial Close SessionADestructiveIdempotent
Close a serial session and release its port lock.
Inputs: sessionId (required). Returns: ok, status, command, data, +9 more
serial_expectSerial ExpectARead-only
Wait for a string pattern in a serial session buffer with timeout.
Inputs: sessionId (required), pattern (required), timeoutMs, caseSensitive, +1 more. Returns: ok, status, command, data, +9 more
serial_list_sessionsSerial List SessionsARead-only
List active serial sessions and current port lock state.
Inputs: no named parameters. Returns: ok, status, command, data, +9 more
serial_open_sessionSerial Open SessionADestructive
Open a stateful serial monitor session with port lock ownership.
Inputs: port (required), baudRate, ttlMs, maxBufferBytes. Returns: ok, status, command, data, +9 more
serial_readSerial ReadARead-only
Read buffered bytes from an open serial session.
Inputs: sessionId (required), fromOffset, maxBytes, encoding. Returns: ok, status, command, data, +9 more
serial_writeSerial WriteADestructive
Write bytes to an open serial session. Safety preflight is enforced unless explicitly skipped.
Inputs: sessionId (required), data (required), encoding, lineEnding, +2 more. Returns: ok, status, command, data, +9 more
upload_and_wait_readyUpload And Wait ReadyADestructive
Upload a sketch and wait for a serial readiness pattern, handling post-upload reset/re-enumeration windows.
Inputs: sketchPath (required), port (required), fqbn, verify, +7 more. Returns: ok, status, command, data, +9 more
upload_sketchUpload SketchBDestructiveIdempotent
Upload a compiled sketch to a connected board/port.
Inputs: sketchPath (required), port (required), fqbn, verify, +3 more. Returns: ok, status, command, data, +9 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
Each tool targets a distinct aspect of the Arduino workflow: installation, board info, compilation, upload, serial operations, and safety checks. Even seemingly overlapping tools like list_connected_boards and list_serial_ports have different purposes (board detection vs port listing). No ambiguity.
Most tools follow verb_noun pattern using underscores (e.g., compile_sketch, detect_hardware). However, a few tools like arduino_cli_doctor and safety_preflight break the pattern by starting with a server-specific prefix or using a verb+noun without underscore. Overall consistent but with minor deviations.
21 tools cover the full Arduino development lifecycle—installation, board management, compilation, upload, serial monitoring, and safety checks. Each tool has a clear role, and the count is appropriate for the domain without being excessive.
The tool surface covers core Arduino CLI operations: installation, board detection, compilation, upload, and serial communication. Minor gaps exist, such as library management (install/list libraries) and core updates, but these are secondary to the main workflow. No critical dead ends.
Maintenance
Related MCP Connectors
AI electronics blueprint generator — BOM, wiring, firmware, renders for Arduino/ESP32/RPi.
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
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.32 PyPI10MIT
- 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.213MIT
- AlicenseBqualityBmaintenanceEnables AI agents to detect boards, manage cores and libraries, compile and upload sketches, and perform serial I/O through a local MCP server.17Apache 2.0