mcp-arduino/docs/QUICK_START.md

🚀 Quick Start Guide

Get up and running with MCP Arduino Server in 5 minutes!

Prerequisites

• Python 3.9+
• Arduino CLI installed
• An Arduino or ESP32 board
• USB cable

1️⃣ Installation

# Using uv (recommended)
uv pip install mcp-arduino-server

# Or using pip
pip install mcp-arduino-server

2️⃣ Configuration

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "arduino": {
      "command": "uv",
      "args": ["run", "mcp-arduino-server"],
      "env": {
        "ARDUINO_SKETCHES_DIR": "~/Documents/Arduino_MCP_Sketches"
      }
    }
  }
}

For Other MCP Clients

Create a .env file:

# Required
ARDUINO_SKETCHES_DIR=~/Documents/Arduino_MCP_Sketches

# Optional (with defaults)
ARDUINO_SERIAL_BUFFER_SIZE=10000
LOG_LEVEL=INFO

3️⃣ First Sketch

Create and Upload

# Create a new sketch
await arduino_create_sketch(sketch_name="Blink")

# Write the code
await arduino_write_sketch(
    sketch_name="Blink",
    content="""
void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  Serial.begin(115200);
  Serial.println("Blink sketch started!");
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  Serial.println("LED ON");
  delay(1000);

  digitalWrite(LED_BUILTIN, LOW);
  Serial.println("LED OFF");
  delay(1000);
}
"""
)

# Find your board
boards = await arduino_list_boards()
# Returns: [{"port": "/dev/ttyUSB0", "fqbn": "arduino:avr:uno", ...}]

# Upload to board
await arduino_upload_sketch(
    sketch_name="Blink",
    port="/dev/ttyUSB0"
)

4️⃣ Serial Monitoring

Connect and Monitor

# Connect to serial port
await serial_connect(
    port="/dev/ttyUSB0",
    baudrate=115200
)

# Read serial data
data = await serial_read(
    port="/dev/ttyUSB0",
    create_cursor=True
)
# Returns data with cursor for pagination

# Send commands
await serial_send(
    port="/dev/ttyUSB0",
    data="HELLO"
)

5️⃣ ESP32 Setup (Optional)

Install ESP32 Support

# One-time setup
await arduino_install_esp32()

# List ESP32 boards
boards = await arduino_list_boards()
# Now includes ESP32 boards

ESP32 Example

# Create ESP32 sketch
await arduino_write_sketch(
    sketch_name="ESP32_WiFi",
    content="""
#include <WiFi.h>

void setup() {
  Serial.begin(115200);
  Serial.println("ESP32 Started!");

  // Print chip info
  Serial.print("Chip Model: ");
  Serial.println(ESP.getChipModel());
  Serial.print("Chip Cores: ");
  Serial.println(ESP.getChipCores());
}

void loop() {
  Serial.print("Free Heap: ");
  Serial.println(ESP.getFreeHeap());
  delay(5000);
}
"""
)

# Upload to ESP32
await arduino_upload_sketch(
    sketch_name="ESP32_WiFi",
    port="/dev/ttyUSB0",
    board_fqbn="esp32:esp32:esp32"
)

🎯 Common Tasks

List Available Ports

ports = await serial_list_ports(arduino_only=True)
# Returns Arduino-compatible ports only

Install Libraries

# Search for libraries
libraries = await arduino_search_libraries(query="servo")

# Install a library
await arduino_install_library(library_name="Servo")

Monitor with Cursor

# Create cursor for continuous reading
result = await serial_read(create_cursor=True)
cursor_id = result['cursor_id']

# Read next batch
while True:
    data = await serial_read(
        cursor_id=cursor_id,
        limit=10
    )
    for entry in data['entries']:
        print(f"{entry['timestamp']}: {entry['data']}")

    if not data['has_more']:
        break

Generate Circuit Diagram

# From description (uses AI)
await wireviz_generate_from_description(
    description="Arduino Uno connected to LED on pin 13 with 220 ohm resistor"
)

# From YAML
await wireviz_generate_from_yaml(
    yaml_content="""
connectors:
  Arduino:
    type: Arduino Uno
    pins: [GND, 13]
  LED:
    type: LED
    pins: [cathode, anode]

cables:
  power:
    connections:
      - Arduino: [13]
      - LED: [anode]
  ground:
    connections:
      - Arduino: [GND]
      - LED: [cathode]
"""
)

⚡ Pro Tips

1. Auto-compile on write: Sketches are automatically compiled when written
2. Buffer management: Adjust ARDUINO_SERIAL_BUFFER_SIZE for your data rate
3. Exclusive mode: Use exclusive=True when connecting to avoid conflicts
4. Auto-reconnect: Serial connections auto-reconnect on disconnect
5. Cursor recovery: Enable auto_recover=True for robust reading

🔍 Next Steps

• Serial Integration Guide - Advanced serial features
• API Reference - Complete tool documentation
• ESP32 Guide - ESP32-specific features
• Examples - More code samples

🆘 Quick Troubleshooting

Problem	Solution
"Port not found"	Check USB connection and drivers
"Permission denied"	Linux/Mac: Add user to dialout group
"Board not detected"	Install board core via arduino_install_core()
"Upload failed"	Check correct port and board selection
"Missing libraries"	Use arduino_install_library()

💬 Getting Help

• Check Documentation Index
• Review Common Issues
• Visit GitHub Issues

---

Ready to build something amazing? You're all set! 🎉