# mcp-for-arduino

![CI](https://github.com/blame-me/arduino-mcp/actions/workflows/ci.yml/badge.svg)
![Release](https://img.shields.io/github/v/release/blame-me/arduino-mcp)
![License](https://img.shields.io/github/license/blame-me/arduino-mcp)

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](https://github.com/blame-me/arduino-mcp/releases/latest):

- **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 Claude Desktop. Then restart Claude Desktop 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.

## Manual setup (developers)

### Prerequisites

1. **Node.js 20+**
2. **arduino-cli** (verified with v1.5.1):
   ```powershell
   # 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](https://arduino.github.io/arduino-cli/latest/installation/).

### Build & run

```powershell
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
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
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`):
```json
{ "mcpServers": { "arduino": { "command": "C:\\path\\to\\mcp-for-arduino.exe" } } }
```

**VS Code / Cursor** (`.vscode/mcp.json` or `~/.cursor/mcp.json`):
```json
{ "servers": { "arduino": { "type": "stdio", "command": "C:\\path\\to\\mcp-for-arduino.exe" } } }
```

**OpenCode** (`opencode.json`):
```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).