MCP Arduino Server (mcp-arduino-server)

A FastMCP-powered bridge exposing arduino-cli functionality via the Model Context Protocol (MCP). Manage sketches, boards, libraries, files, plus generate WireViz schematics from YAML or natural language.

Requirements

Python ≥3.10
arduino-cli in PATH
MCP SDK (mcp[cli])
WireViz (optional; for diagram generation)
OPENAI_API_KEY (for AI‑powered WireViz)
thefuzz[speedup] (optional; enables fuzzy local library search)

Installation

From PyPI:

pip install mcp-arduino-server

From source:

git clone https://github.com/Volt23/mcp-arduino-server.git
cd mcp-arduino-server
pip install .

Configuration

Environment variables override defaults:

Variable	Default / Description
ARDUINO_CLI_PATH	auto-detected
WIREVIZ_PATH	auto-detected
MCP_SKETCH_DIR	`~/Documents/Arduino_MCP_Sketches/`
LOG_LEVEL	`INFO`
OPENAI_API_KEY	your OpenAI API key (required for AI‑powered WireViz)
OPENROUTER_API_KEY	optional alternative to `OPENAI_API_KEY`
ARDUINO_SERIAL_LOG_MAX_BYTES	max size per serial log file (bytes; 0 disables)
ARDUINO_SERIAL_LOG_ROTATE_COUNT	number of rotated serial logs to keep

Quick Start

mcp-arduino-server

Server listens on STDIO for JSON-RPC MCP calls. Key methods:

Sketches

create_new_sketch(name)
list_sketches()
read_file(path)
write_file(path, content[, board_fqbn]) (auto-compiles & opens .ino)

Build & Deploy

verify_code(sketch, board_fqbn)
upload_sketch(sketch, port, board_fqbn)

Libraries

lib_search(name[, limit])
lib_install(name)
list_library_examples(name)

Boards

list_boards()
board_search(query)

Serial Monitor

serial_monitor_start(port, baud, buffer_lines, log_to_file, ...)
serial_monitor_read(monitor_id, lines)
serial_monitor_list()
serial_monitor_stop(monitor_id)

File Ops

rename_file(src, dest)
remove_file(path) (destructive; operations sandboxed to home & sketch directories)

WireViz Diagrams

generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit") (AI‑powered; requires OPENAI_API_KEY, opens PNG automatically)

MCP Client Configuration

To integrate with MCP clients (e.g., Claude Desktop), set your OpenAI API key in the environment (or alternatively OPENROUTER_API_KEY for OpenRouter):

{
  "mcpServers": {
    "arduino": {
      "command": "/path/to/mcp-arduino-server",
      "args": [],
      "env": {
        "WIREVIZ_PATH": "/path/to/wireviz",
        "OPENAI_API_KEY": "<your-openai-api-key>"
      }
    }
  }
}

Troubleshooting

Set LOG_LEVEL=DEBUG for verbose logs.
Verify file and serial-port permissions.
Install missing cores: arduino-cli core install <spec>.
Run arduino-cli commands manually to debug.

License

MIT