mcp-arduino

This MCP server exposes Arduino tooling via the Model Context Protocol, allowing MCP clients to manage Arduino sketches, boards, libraries, files, and to generate WireViz diagrams from description inputs. Once started, the server listens for JSON-RPC MCP calls on STDIO and exposes a suite of categories: Sketches (create, list, read, write with auto-compile and open), Build & Deploy (verify and upload to boards), Libraries (search, install, view examples), Boards (list and search available boards), Serial Monitor (start, read, list, stop), File Operations (rename and remove with sandboxing), and WireViz (generate circuit diagrams from natural language or YAML descriptions). For AI-powered WireViz, provide an OpenAI API key via OPENAI_API_KEY or OPENROUTER_API_KEY for alternative routing. Use the MCP client configuration example to wire this server into your MCP client toolchain.

Prerequisites:

• Python 3.10 or newer
• arduino-cli installed and available in PATH (for sketch operations)
• MCP SDK (mcp[cli]) installed in your environment
• WireViz installed if you want circuit diagrams
• OPENAI_API_KEY for AI-powered WireViz (optional but required for AI features)

Install from PyPI:

pip install mcp-arduino-server

Or install from source:

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

Run the server (example):

mcp-arduino-server  # requires that the package exposes a console entry point

If you prefer running as a module:

python -m mcp_arduino_server

Configure the MCP client to connect to this server using the provided mcp_config snippet and ensure environment variables are properly set for Arduino CLI, WireViz, and AI keys.

Tips and common issues:

• Ensure arduino-cli is installed and accessible in PATH for sketch operations.
• If WireViz diagrams fail to generate, verify WIREVIZ_PATH and OPENAI_API_KEY (or OPENROUTER_API_KEY) are correctly set.
• For large serial logs, adjust ARDUINO_SERIAL_LOG_MAX_BYTES and ARDUINO_SERIAL_LOG_ROTATE_COUNT as needed.
• When running from source, install development requirements if listed in the repo (dependencies may include thefuzz[speedup] for faster library searching).
• Permissions: the server sandboxes file operations to the home and sketch directories—grant appropriate permissions to avoid access errors.
• Debugging: run with LOG_LEVEL=DEBUG to obtain verbose logs for troubleshooting.