Skip to main content
Glama
arduino-mcp-server

arduino-mcp-server

by hardware-mcp

arduino-mcp-server

npm version License: MIT Node.js 20+

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

Add 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

arduino_cli_doctor

Check Arduino CLI installation and version

install_arduino_cli

Guide through arduino-cli installation

detect_hardware

Detect connected boards and infer FQBNs

list_connected_boards

List all connected Arduino boards

list_serial_ports

List available serial ports

ensure_core_installed

Check/install board cores

compile_sketch

Compile a sketch for a target board

upload_sketch

Upload compiled sketch to a board

upload_and_wait_ready

Upload and wait for device ready signal

serial_open_session

Open a stateful serial session

serial_read

Read buffered serial data

serial_expect

Wait for a pattern in serial output

serial_write

Send data over serial

serial_close_session

Close a serial session

serial_list_sessions

List active serial sessions

read_serial_snapshot

Quick one-shot serial read

safety_preflight

Electrical safety check before hardware ops

get_board_details

Get pin/capability details for a board

list_supported_boards

List all boards arduino-cli supports

list_board_reference

Browse board pin reference

search_board_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 behavior

  • arduino-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 1C

  • BATTERY_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

ARDUINO_CLI_PATH

arduino-cli

Path to arduino-cli binary

ARDUINO_SKETCH_ROOT

(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 dev

Part 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

Open an issue

Available Tools

21 tools
arduino_cli_doctorArduino CLI DoctorA
Read-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 SketchA
DestructiveIdempotent

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 HardwareB
Read-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 InstalledA
DestructiveIdempotent

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 DetailsA
Read-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 CLIA
DestructiveIdempotent

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 ReferenceA
Read-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 BoardsA
Read-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 PortsA
Read-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 BoardsA
Read-only

List supported/installable boards from the local arduino-cli index.

Inputs: search. Returns: ok, status, command, data, +9 more

read_serial_snapshotRead Serial SnapshotB
Read-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 PreflightA
Read-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 ReferenceA
Read-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 SessionA
DestructiveIdempotent

Close a serial session and release its port lock.

Inputs: sessionId (required). Returns: ok, status, command, data, +9 more

serial_expectSerial ExpectA
Read-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 SessionsA
Read-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 SessionA
Destructive

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 ReadA
Read-only

Read buffered bytes from an open serial session.

Inputs: sessionId (required), fromOffset, maxBytes, encoding. Returns: ok, status, command, data, +9 more

serial_writeSerial WriteA
Destructive

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

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 SketchB
DestructiveIdempotent

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

    A3.8/5.0

    Scored across 21 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers