arduino-claude-mcp

MCP server for Arduino IDE 2.0 sketches. It exposes a small REST API plus an MCP stdio bridge so agents can read and write the main .ino file, list sources, and optionally compile with arduino-cli.

Features

• Validate an Arduino sketch folder

• Read and write source files (defaults to main .ino)

• List .ino/.h/.cpp/.c files

• Compile with arduino-cli (optional)

• REST + MCP stdio transport

Related MCP server: agent-coordination-mcp

Requirements

• An Arduino sketch folder (Arduino IDE 2.0 format)

• Node.js 18+

• Optional: arduino-cli for builds

Installation

Global install:

npm install -g arduino-claude-mcp

Local dev:

npm install
npm run build
npm run build:mcp

Container image:

docker pull eoinedge/arduino-mcp:latest

Usage

Run the REST server

arduino-claude-mcp

Defaults to port 3080. Override with:

$env:PORT=3081
arduino-claude-mcp

Run with Docker (Pi/OpenClaw)

docker run --rm --network host \
  -e PORT=3080 \
  -e ARDUINO_FQBN=arduino:mbed_nano:nano33ble \
  -v /home/pi/pi-openclaw-mcp-stack/workspace/Arduino:/workspace \
  eoinedge/arduino-mcp:latest

Run the MCP stdio server

node build/mcp.js

If your REST server is not on the default port, set one of:

• ARDUINO_API_URL (full URL, for example http://localhost:3081)

• ARDUINO_API_PORT (port only, for example 3081)

MCP client config

{
  "mcpServers": {
    "arduino-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/build/mcp.js"]
    }
  }
}

Tutorial (10 minutes)

1. Create a sketch folder whose main .ino matches the folder name.

2. Validate it:

   • POST /validate

   • Body: { "projectRoot": "/path/to/MySketch" }

3. Read the main sketch:

   • POST /read_source

   • Body: { "projectRoot": "/path/to/MySketch" }

4. Write a small change:

   • POST /write_source

   • Body: { "projectRoot": "/path/to/MySketch", "content": "// your code" }

5. Build (optional):

   • Set ARDUINO_FQBN (example arduino:avr:uno)

   • POST /build

   • Body: { "projectRoot": "/path/to/MySketch" }

Environment variables

• PORT: REST server port (default 3080)

• ARDUINO_API_URL: REST base URL for the MCP bridge

• ARDUINO_API_PORT: REST port for the MCP bridge

• ARDUINO_CLI: arduino-cli executable (default arduino-cli)

• ARDUINO_FQBN: fully qualified board name for compile

• ARDUINO_BUILD_TIMEOUT_MS: build timeout in ms (default 120000)

REST API

Health

• GET /health -> { status: "ok" }

Validate

• POST /validate body: { projectRoot: string }

• Returns { valid, inoPath, projectRoot }

List sources

• POST /list_sources body: { projectRoot: string }

• Returns { files: string[] }

Read source

• POST /read_source body: { projectRoot: string, relativePath?: string }

• Returns { path, content }

Write source

• POST /write_source body: { projectRoot: string, relativePath?: string, content: string }

• Returns { success, path, bytes }

Append source

• POST /append_source body: { projectRoot: string, relativePath?: string, content: string }

• Returns { success, path, bytes }

Build

• POST /build body: { projectRoot: string, timeoutMs?: number }

• Returns { success, exitCode, stdout, stderr }

• Requires arduino-cli and ARDUINO_FQBN

Clawdbot / Moltbot compatibility

This repo ships a skill at skills/arduino-mcp/SKILL.md.

Enable it in Moltbot:

{
  "skills": {
    "load": {
      "extraDirs": ["~/.clawdbot/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "entries": {
      "arduino-mcp": {
        "enabled": true,
        "env": {}
      }
    }
  }
}

Example prompts

• "Open this Arduino sketch and add a blinking LED on pin 13."

• "List all source files and explain what each does."

• "Append a serial debug line and recompile for an Uno board."

Testing

npm test

Tests use a temporary sketch folder and do not require arduino-cli.

Publishing

1. Update package.json version

2. Build:

   npm run build
   npm run build:mcp

3. Publish:

   npm publish --access public

4. Tag and push to trigger .github/workflows/publish.yml

Docker publishing

Manual push:

docker login
docker buildx build --platform linux/amd64,linux/arm64 \
  -t eoinedge/arduino-mcp:latest \
  -t eoinedge/arduino-mcp:<version> \
  --push .

GitHub Actions:

• docker-publish.yml pushes Docker images on main and version tags.

• Required repo secrets:

  • DOCKERHUB_USERNAME

  • DOCKERHUB_TOKEN

Project structure

• src/index.ts REST API

• src/mcp.ts MCP stdio bridge

• skills/arduino-mcp/SKILL.md agent skill

• server.json MCP registry metadata

Contributing

PRs welcome. Please keep changes small and include tests where possible.

License

MIT