mcp-arduino/docs/CONFIGURATION.md

⚙️ Configuration Guide

Complete configuration reference for MCP Arduino Server

📋 Environment Variables

Required Variables

ARDUINO_SKETCHES_DIR

• Description: Directory where Arduino sketches are stored
• Default: None (required)
• Example: ~/Documents/Arduino_MCP_Sketches

export ARDUINO_SKETCHES_DIR="$HOME/Documents/Arduino_MCP_Sketches"

Optional Variables

ARDUINO_SERIAL_BUFFER_SIZE

• Description: Maximum entries in circular buffer for serial data
• Default: 10000
• Range: 100 to 1000000
• Guidance:
  • Small systems: 1000 (minimal memory usage)
  • Normal use: 10000 (balanced performance)
  • High-speed logging: 100000 (captures more before wraparound)
  • Data analysis: 1000000 (maximum retention)

export ARDUINO_SERIAL_BUFFER_SIZE=50000  # For high-speed data

ARDUINO_CLI_PATH

• Description: Path to Arduino CLI executable
• Default: /usr/local/bin/arduino-cli
• Auto-detection: System PATH is searched if not set

export ARDUINO_CLI_PATH=/opt/arduino/arduino-cli

WIREVIZ_PATH

• Description: Path to WireViz executable for circuit diagrams
• Default: /usr/local/bin/wireviz
• Required for: Circuit diagram generation

export WIREVIZ_PATH=/usr/local/bin/wireviz

ENABLE_CLIENT_SAMPLING

• Description: Enable AI features using client-side LLM
• Default: true
• Values: true or false
• Note: No API keys required when enabled

export ENABLE_CLIENT_SAMPLING=true

LOG_LEVEL

• Description: Logging verbosity
• Default: INFO
• Values: DEBUG, INFO, WARNING, ERROR, CRITICAL

export LOG_LEVEL=DEBUG  # For troubleshooting

🔧 Configuration Methods

Method 1: Environment File (.env)

Create a .env file in your project directory:

# .env file
ARDUINO_SKETCHES_DIR=~/Documents/Arduino_MCP_Sketches
ARDUINO_SERIAL_BUFFER_SIZE=10000
ARDUINO_CLI_PATH=/usr/local/bin/arduino-cli
WIREVIZ_PATH=/usr/local/bin/wireviz
ENABLE_CLIENT_SAMPLING=true
LOG_LEVEL=INFO

Method 2: Claude Desktop Config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Method 3: Shell Export

Set in your shell profile (~/.bashrc, ~/.zshrc, etc.):

# Arduino MCP Server
export ARDUINO_SKETCHES_DIR="$HOME/Documents/Arduino_MCP_Sketches"
export ARDUINO_SERIAL_BUFFER_SIZE=10000
export LOG_LEVEL=INFO

Method 4: Docker Compose

Using environment variables in docker-compose.yml:

services:
  arduino-mcp:
    image: mcp-arduino-server
    environment:
      - ARDUINO_SKETCHES_DIR=/sketches
      - ARDUINO_SERIAL_BUFFER_SIZE=50000
      - LOG_LEVEL=DEBUG
    volumes:
      - ./sketches:/sketches
      - /dev:/dev  # For serial port access
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    privileged: true  # Required for device access

🔑 Permissions

Linux

Add user to dialout group for serial port access:

sudo usermod -a -G dialout $USER
# Logout and login for changes to take effect

macOS

No special permissions needed for USB serial devices.

Windows

Install appropriate USB drivers for your Arduino board.

📁 Directory Structure

The server expects this structure:

$ARDUINO_SKETCHES_DIR/
├── MySketch/
│   ├── MySketch.ino
│   └── data/           # Optional SPIFFS/LittleFS data
├── ESP32_Project/
│   ├── ESP32_Project.ino
│   ├── config.h
│   └── wifi_credentials.h
└── libraries/          # Local libraries (optional)

🎯 Configuration Profiles

Development Profile

# .env.development
ARDUINO_SKETCHES_DIR=~/Arduino/dev_sketches
ARDUINO_SERIAL_BUFFER_SIZE=100000
LOG_LEVEL=DEBUG
ENABLE_CLIENT_SAMPLING=true

Production Profile

# .env.production
ARDUINO_SKETCHES_DIR=/var/arduino/sketches
ARDUINO_SERIAL_BUFFER_SIZE=10000
LOG_LEVEL=WARNING
ENABLE_CLIENT_SAMPLING=true

Memory-Constrained Profile

# .env.embedded
ARDUINO_SKETCHES_DIR=/tmp/sketches
ARDUINO_SERIAL_BUFFER_SIZE=1000  # Minimal buffer
LOG_LEVEL=ERROR
ENABLE_CLIENT_SAMPLING=false

🔍 Configuration Validation

Check your configuration:

# Test configuration
import os

print("Configuration Check:")
print(f"Sketches Dir: {os.getenv('ARDUINO_SKETCHES_DIR', 'NOT SET')}")
print(f"Buffer Size: {os.getenv('ARDUINO_SERIAL_BUFFER_SIZE', '10000')}")
print(f"Log Level: {os.getenv('LOG_LEVEL', 'INFO')}")

# Verify directories exist
sketches_dir = os.path.expanduser(os.getenv('ARDUINO_SKETCHES_DIR', ''))
if os.path.exists(sketches_dir):
    print(f"✓ Sketches directory exists: {sketches_dir}")
else:
    print(f"✗ Sketches directory not found: {sketches_dir}")

🐳 Docker Configuration

Dockerfile with Configuration

FROM python:3.11-slim

# Install Arduino CLI
RUN apt-get update && apt-get install -y \
    wget \
    && wget https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz \
    && tar -xzf arduino-cli_latest_Linux_64bit.tar.gz -C /usr/local/bin \
    && rm arduino-cli_latest_Linux_64bit.tar.gz

# Install MCP Arduino Server
RUN pip install mcp-arduino-server

# Set default environment variables
ENV ARDUINO_SKETCHES_DIR=/sketches
ENV ARDUINO_SERIAL_BUFFER_SIZE=10000
ENV LOG_LEVEL=INFO

# Create sketches directory
RUN mkdir -p /sketches

# Run server
CMD ["mcp-arduino-server"]

Docker Run Command

docker run -it \
  -e ARDUINO_SKETCHES_DIR=/sketches \
  -e ARDUINO_SERIAL_BUFFER_SIZE=50000 \
  -v $(pwd)/sketches:/sketches \
  --device /dev/ttyUSB0 \
  --privileged \
  mcp-arduino-server

🔧 Advanced Configuration

Custom Arduino CLI Config

Create ~/.arduino15/arduino-cli.yaml:

board_manager:
  additional_urls:
    - https://arduino.esp8266.com/stable/package_esp8266com_index.json
    - https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

daemon:
  port: "50051"

directories:
  data: ~/.arduino15
  downloads: ~/.arduino15/staging
  user: ~/Arduino

library:
  enable_unsafe_install: false

logging:
  level: info
  format: text

Serial Port Aliases (Linux)

Create consistent device names using udev rules:

# /etc/udev/rules.d/99-arduino.rules
SUBSYSTEM=="tty", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0043", SYMLINK+="arduino_uno"
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", SYMLINK+="arduino_nano"

Then use: /dev/arduino_uno instead of /dev/ttyUSB0

🆘 Troubleshooting Configuration

Issue: "ARDUINO_SKETCHES_DIR not set"

Solution: Set the required environment variable:

export ARDUINO_SKETCHES_DIR="$HOME/Documents/Arduino_MCP_Sketches"

Issue: "Permission denied on /dev/ttyUSB0"

Solution (Linux):

sudo usermod -a -G dialout $USER
# Then logout and login

Issue: "Buffer overflow - missing data"

Solution: Increase buffer size:

export ARDUINO_SERIAL_BUFFER_SIZE=100000

Issue: "arduino-cli not found"

Solution: Install Arduino CLI:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

📊 Performance Tuning

Buffer Size Guidelines

Data Rate	Buffer Size	Memory Usage	Use Case
< 10 Hz	1,000	~100 KB	Basic debugging
< 100 Hz	10,000	~1 MB	Normal operation
< 1 kHz	100,000	~10 MB	High-speed logging
Any	1,000,000	~100 MB	Long-term analysis

Memory Calculation

# Estimate memory usage
buffer_size = int(os.getenv('ARDUINO_SERIAL_BUFFER_SIZE', '10000'))
bytes_per_entry = 100  # Approximate
memory_mb = (buffer_size * bytes_per_entry) / (1024 * 1024)
print(f"Estimated memory usage: {memory_mb:.1f} MB")

🔐 Security Considerations

1. Sketches Directory: Ensure proper permissions on sketches directory
2. Serial Ports: Limit device access to trusted USB devices
3. Client Sampling: Disable if not using AI features to reduce attack surface
4. Docker: Avoid --privileged if possible; use specific device mappings

📝 Example Configuration Files

Complete .env.example is provided in the repository:

cp .env.example .env
# Edit .env with your settings

---

For more help, see Troubleshooting Guide or Quick Start