arduino-agent-mcp

AI-native Arduino development via Model Context Protocol (MCP)

arduino-agent-mcp is an open-source platform designed to give AI agents (like Gemini, Claude, etc.) safe, deterministic, and powerful control over Arduino hardware. It acts as a bridge between LLMs and embedded hardware, enabling semantic understanding of boards, libraries, and firmware.

Unlike simple CLI wrappers, this project provides a structured state machine for hardware, handling dependency resolution, multi-board orchestration, and safety checks before any code touches silicon.

🌟 Features

🧠 Core Agentic Capabilities

• Semantic Board Awareness: Agents don't guess pins; they query list_boards to understand architecture, ports, and capabilities.
• Safe Library Management: Automated dependency resolution and installation (resolve_library).
• Structured Compilation: JSON-based compiler output for AI self-correction.

🛡️ Safety & Reliability

• Hardware Assertions: Pre-upload checks (hardware_check) for voltage, conflicts, and more.
• Firmware Rollback: Automatic snapshots of successful builds allow one-click recovery.
• Compilation-First: Code is never uploaded without a clean build.

🚀 Advanced Tooling

• Multi-Board Orchestration: Manage fleets of devices (e.g., Sensor Node + Gateway) via select_board.
• Power Profiling: Static analysis and runtime estimation of power consumption (estimate_power).
• Schematic Generation: Turn code/intent into Graphviz/Mermaid diagrams (generate_schematic).
• OTA Updates: Safe Over-The-Air updates for ESP32/WiFi boards (ota_upload).

🏗️ Architecture

The system is a modular MCP Server built on Node.js that wraps the Arduino CLI.

graph TD
    AI[AI Agent] <-->|MCP Protocol| MCP[Arduino MCP Server]
    MCP <-->|JSON/IPC| CLI[Arduino CLI]
    CLI <-->|Serial/USB| BOARD[Arduino Hardware]
    
    subgraph "MCP Server Logic"
        ORCH[Board Orchestrator]
        SAFE[Safety Checks]
        LIB[Dep Resolver]
        PROF[Power Profiler]
    end
    
    MCP --- ORCH
    MCP --- SAFE
    MCP --- LIB
    MCP --- PROF

See docs/architecture.md for a deep dive.

📦 Project Structure

arduino-agent-mcp/
├── packages/
│   ├── mcp-server/          # Main MCP Server (Node.js)
│   ├── cli/                 # (Future) User CLI
│   ├── templates/           # Starter templates (Simple/Advanced)
│   ├── schematics/          # Schematic generation assets
│   └── power-profiles/      # Board power definition models
├── docs/                    # Documentation
└── examples/                # Example usage patterns

🚀 Getting Started

Prerequisites

• Node.js >= 18 LTS
• Arduino CLI installed and in your PATH.

Installation

1. Clone the repository:

   git clone https://github.com/your-org/arduino-agent-mcp.git
   cd arduino-agent-mcp
   

2. Install dependencies:

   cd packages/mcp-server
   npm install
   

3. Build the server:

   $npm run build
   

4. Configure your AI Client (e.g., Claude Desktop, Gemini) to use the MCP server.

Development

We welcome contributions! Please see CONTRIBUTING.md.

Docker Support

This project is container-ready and follows Apify Actor standards.

1. Build Container:

   cd packages/mcp-server
   docker build -t arduino-mcp .
   

2. Run (Stdio Mode):

   $docker run -i arduino-mcp
   

Note: When running in Docker/Cloud, physical hardware features (upload, monitor) are disabled unless you use the Network Serial Bridge.

🔌 Network Serial Bridge (Remote Upload)

If running the MCP server in a container or cloud, you can use the bridge-client to flash code to your local machine.

1. Start Bridge (Locally):

   cd packages/bridge-client
   npm install
   npm start
   # Bridge listening on port 3000
   

2. Expose Bridge (via ngrok):

   ngrok http 3000
   # Copy the URL (e.g. https://xyz.ngrok.io)
   

3. Run MCP Server (Remote):

   $docker run -e BRIDGE_URL=https://xyz.ngrok.io -i arduino-mcp
   

The agent will now automatically route uploads through the bridge.

📜 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.