{
  "markdown": "# arduino-mcp-server\n\n[![npm version](https://img.shields.io/npm/v/arduino-mcp-server)](https://www.npmjs.com/package/arduino-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n\n**Give your AI assistant full control over Arduino — compile, upload, monitor serial, and verify wiring safety, all through natural language.**\n\nPart of the [HardwareMCP](https://github.com/hardware-mcp) ecosystem — open-source MCP servers that bridge AI to physical hardware.\n\n---\n\n## What this does\n\nAI assistants can control Jira, GitHub, and databases. They can't talk to a microcontroller — until now.\n\n`arduino-mcp-server` wraps `arduino-cli` into an MCP server so your AI can:\n\n- **Detect** connected boards and ports automatically\n- **Compile and upload** sketches without touching the terminal\n- **Monitor serial output** with stateful sessions (open, read, expect, write, close)\n- **Run electrical safety checks** before sending commands to hardware\n- **Manage dependencies** — cores, libraries, and CLI installation\n\n---\n\n## Quick Start\n\n**Install:**\n```bash\nnpm install -g arduino-mcp-server\n```\n\n**Add to Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"arduino\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"arduino-mcp-server\"],\n      \"env\": {\n        \"ARDUINO_CLI_PATH\": \"arduino-cli\",\n        \"ARDUINO_SKETCH_ROOT\": \"/path/to/your/sketches\"\n      }\n    }\n  }\n}\n```\n\nRequires [arduino-cli](https://arduino.github.io/arduino-cli/) on your PATH, or let the server install it for you.\n\n---\n\n## What you can say\n\n**Bootstrap from scratch:**\n> \"Check if Arduino CLI is installed and set everything up for an Arduino Uno.\"\n\n**Compile and upload:**\n> \"Compile my Blink sketch and upload it to the Uno on COM6.\"\n\n**Serial monitoring:**\n> \"Open serial on COM6 at 115200 and wait until the device prints READY.\"\n\n**Safety-first workflows:**\n> \"Run a safety preflight for an Arduino Uno with 5V on pin 13 at 25mA before I send commands.\"\n\n---\n\n## Tools\n\n| Tool | What it does |\n|------|-------------|\n| `arduino_cli_doctor` | Check Arduino CLI installation and version |\n| `install_arduino_cli` | Guide through arduino-cli installation |\n| `detect_hardware` | Detect connected boards and infer FQBNs |\n| `list_connected_boards` | List all connected Arduino boards |\n| `list_serial_ports` | List available serial ports |\n| `ensure_core_installed` | Check/install board cores |\n| `compile_sketch` | Compile a sketch for a target board |\n| `upload_sketch` | Upload compiled sketch to a board |\n| `upload_and_wait_ready` | Upload and wait for device ready signal |\n| `serial_open_session` | Open a stateful serial session |\n| `serial_read` | Read buffered serial data |\n| `serial_expect` | Wait for a pattern in serial output |\n| `serial_write` | Send data over serial |\n| `serial_close_session` | Close a serial session |\n| `serial_list_sessions` | List active serial sessions |\n| `read_serial_snapshot` | Quick one-shot serial read |\n| `safety_preflight` | Electrical safety check before hardware ops |\n| `get_board_details` | Get pin/capability details for a board |\n| `list_supported_boards` | List all boards arduino-cli supports |\n| `list_board_reference` | Browse board pin reference |\n| `search_board_reference` | Search board reference by keyword |\n\n**Resources:**\n- `arduino://boards/reference` — structured board pin/capability reference\n\n**Prompts:**\n- `arduino-cli-bootstrap-policy` — policy for arduino-cli setup behavior\n- `arduino-setup-assistant` — guided Arduino environment setup\n\n---\n\n## Safety preflight guardrails\n\n`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:\n\n**Battery charge-rate (C-rate) check** — pass a `battery` object (`capacityMah`, `chargeCurrentMa`, `chemistry`) and the check computes `chargeCurrentMa / batteryCapacityMah` and flags it:\n- **`BATTERY_CRATE_UNSAFE`** (hard, blocking) above 1C\n- **`BATTERY_CRATE_CAUTION`** (soft, non-blocking) above 0.5C\n\nGeneric 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.\n\n**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.\n\n**ESP32-family pin safety** (table-driven per board via `data/board-reference.json`):\n- **SPI-flash pins** (GPIO6-11 on classic ESP32 WROOM/WROVER modules) — hard error (`SPI_FLASH_PIN_USED`); wiring these prevents boot.\n- **Boot-strapping pins** (GPIO0/2/12/15 on classic ESP32) — caution; usable at runtime but risky if externally held during boot/reset (existing check).\n- **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.\n- **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.\n\nBoard data for all of the above lives in JSON, keyed by board id/FQBN, so more boards can be added without touching guardrail logic.\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ARDUINO_CLI_PATH` | `arduino-cli` | Path to arduino-cli binary |\n| `ARDUINO_SKETCH_ROOT` | *(none)* | Restrict sketch paths to this directory |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/hardware-mcp/arduino-mcp-server\ncd arduino-mcp-server\nnpm install\nnpm run typecheck\nnpm test\nnpm run build\nnpm run dev\n```\n\n---\n\n## Part of HardwareMCP\n\nThis server is part of the [HardwareMCP](https://github.com/hardware-mcp) ecosystem — a collection of MCP servers that give AI assistants real control over physical hardware.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Support\n\n[Open an issue](https://github.com/hardware-mcp/arduino-mcp-server/issues)\n",
  "bytes": 7097,
  "sha": "6b685d29d637f9f4a6347a1217b184babcb639248ea3861aefe7d7ab87c99260",
  "repo_slug": "hardware-mcp/arduino-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hardware_mcp_arduino_mcp_serve_359ef28f/readme"
}