MCP Arduino Server

You can run a lightweight MCP server that bridges Arduino CLI functionality into the Model Context Protocol ecosystem. This server lets you manage sketches, boards, libraries, and files, with optional AI-powered WireViz diagram generation for YAML or natural language descriptions, all through a consistent MCP client workflow.

How to use

You interact with the Arduino MCP server through an MCP client, sending requests that map to sketch, library, board, file, serial monitor, and WireViz diagram operations. The server runs locally and exposes a standard set of methods that let you create, read, write, verify, build, upload, search, and manage resources. Start by launching the server, then configure your MCP client to point at the provided command and environment so the client can send the correct requests.

How to install

Prerequisites you need before installing are Python 3.10 or newer, arduino-cli available in your PATH, the MCP SDK (mcp[cli]), and optional tools for WireViz diagrams and AI-powered features if you want advanced diagram generation.

pip install mcp-arduino-server

Configuration and usage notes

Configure environment variables to customize paths and behaviors. Common options include setting the Arduino CLI path, WireViz location, and your OpenAI API key for AI-powered diagram generation. You can override defaults with these variables in your shell or container environment.

MCP Client Configuration

To integrate with an MCP client, specify the stdio configuration that starts the server and provides necessary environment variables. The following example demonstrates how to wire the client to the Arduino MCP server.

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

Troubleshooting

If you encounter issues, enable verbose logging by setting LOG_LEVEL=DEBUG and verify permissions for files and serial ports. Ensure arduino-cli cores are installed and accessible, and run arduino-cli commands manually to isolate problems.

Configuration details

The server can be configured with a set of environment variables to control its behavior. These variables let you keep default paths, enable or disable features, and supply keys required for AI-powered components.

Notes on capabilities

The MCP server exposes a collection of operations grouped into sketches, build & deploy, libraries, boards, serial monitor, file operations, and WireViz diagram generation. You can create new sketches, list and read files, verify and upload code to boards, search and install libraries, list and search boards, and generate circuit diagrams from descriptions.

Supported tools and endpoints

• Create new sketch: create_new_sketch(name)
• List sketches: list_sketches()
• Read file: read_file(path)
• Write file: write_file(path, content[, board_fqbn])
• Verify code: verify_code(sketch, board_fqbn)
• Upload sketch: upload_sketch(sketch, port, board_fqbn)
• Library search: lib_search(name[, limit])
• Library install: lib_install(name)
• List library examples: list_library_examples(name)
• List boards: list_boards()
• Board search: board_search(query)
• Serial monitor actions: serial_monitor_start, serial_monitor_read, serial_monitor_list, serial_monitor_stop
• Rename and remove files: rename_file(src, dest), remove_file(path)
• WireViz diagram from description: generate_circuit_diagram_from_description(desc, sketch, output_base) These tools enable end-to-end development workflows from code creation to visualization.

Security and best practices

Keep your API keys secure. When using AI-powered features, supply keys only to trusted environments. Limit file system operations to sandboxed sketch and home directories to avoid accidental data exposure.

Available tools

Sketch management

Create, read, write, and manage Arduino sketches and their files within the MCP sketch directory.

Build and deploy

Verify code, compile, and upload sketches to boards via arduino-cli."

Library management

Search, install, and list examples for libraries integrated with sketches.

Board management

List available boards and searchboards compatible with your setup.

Serial monitor

Start, read, and stop serial monitors for connected devices.

WireViz generation

AI-powered circuit diagram generation from YAML or natural language descriptions.

File operations

Rename, remove, and manage files within authorized sandboxed areas.