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