{"id":34599256,"url":"https://github.com/niradler/arduino-mcp","last_synced_at":"2026-05-19T16:02:25.629Z","repository":{"id":324594274,"uuid":"1097767961","full_name":"niradler/arduino-mcp","owner":"niradler","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-10T23:29:44.000Z","size":64,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-11T11:52:04.089Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niradler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-16T19:39:26.000Z","updated_at":"2025-12-10T23:29:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niradler/arduino-mcp","commit_stats":null,"previous_names":["niradler/arduino-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/niradler/arduino-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Farduino-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Farduino-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Farduino-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Farduino-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niradler","download_url":"https://codeload.github.com/niradler/arduino-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Farduino-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28002250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T12:07:55.752Z","updated_at":"2025-12-24T12:08:11.791Z","avatar_url":"https://github.com/niradler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arduino MCP Server\n\nA comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Arduino CLI interactions, built with [FastMCP](https://gofastmcp.com/). This server enables AI agents to seamlessly interact with Arduino CLI for development, debugging, code verification, and more.\n\n## Features\n\n### 🛠️ **Tools** (All 3 MCP Pillars)\n\n- **CLI Management**: Check installation, get help for commands\n- **Board Detection**: List connected boards, find Arduino ports, auto-detect best port\n- **Core Management**: Search, install, and list Arduino cores\n- **Library Management**: Search, install, and list Arduino libraries\n- **Sketch Operations**: Create, compile, and upload sketches\n- **Enhanced Serial Monitor**: Bidirectional communication, buffering, file export\n- **Image Conversion**: Convert images to C arrays for display applications (requires ImageMagick)\n- **Configuration**: Initialize config, clean cache\n\n### 📚 **Resources**\n\n- `sketch://{path}` - Read Arduino sketch files (.ino, .cpp, .h)\n- `arduino-config://main` - Access Arduino CLI configuration\n- `board-info://{fqbn}` - Get detailed board information\n\n### 💡 **Prompts**\n\n- **Blink LED Example**: Basic LED blinking sketch template\n- **Sensor Reading Example**: Analog sensor reading template\n- **Sketch Project Workflow**: IDE-like experience with board attach\n- **Full Development Workflow**: Complete Arduino development guide\n- **Troubleshooting Guide**: Common issues and solutions\n\n### 🚀 **Advanced Features**\n\n- **Logging**: Comprehensive logging with info, warning, error levels ([source](https://gofastmcp.com/servers/logging))\n- **Progress Reporting**: Real-time progress updates for long operations ([source](https://gofastmcp.com/servers/progress))\n- **Context Integration**: Full MCP context support for enhanced interactions ([source](https://gofastmcp.com/servers/context))\n- **Annotations**: Proper tool annotations for better UX (readOnly, destructive, openWorld hints)\n\n## Prerequisites\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) (Python package manager)\n- [Arduino CLI](https://arduino.github.io/arduino-cli/latest/installation/)\n- [ImageMagick](https://imagemagick.org/script/download.php) (optional, for image conversion)\n\n## Environment Variables\n\nCustomize the server behavior with these optional environment variables:\n\n| Variable                     | Default       | Description                         |\n| ---------------------------- | ------------- | ----------------------------------- |\n| `ARDUINO_CLI_PATH`           | `arduino-cli` | Path to Arduino CLI executable      |\n| `MCP_SKETCH_DIR`             | OS-specific\\* | Override default sketch directory   |\n| `ARDUINO_SERIAL_BUFFER_SIZE` | `10`          | Serial buffer size in MB            |\n| `ARDUINO_CONFIG_FILE`        | Auto-detected | Custom Arduino CLI config file path |\n\n\\*Default sketch directories:\n\n- Windows: `%DOCUMENTS%\\Arduino`\n- macOS: `~/Documents/Arduino`\n- Linux: `~/Arduino`\n\n## Installation\n\n1. Clone this repository:\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd arduino-mcp\n```\n\n2. Install dependencies with uv:\n\n```bash\nuv sync\n```\n\n3. Install Arduino CLI:\n\n```bash\n# Windows (using winget)\nwinget install ArduinoSA.CLI\n\n# macOS\nbrew install arduino-cli\n\n# Linux\ncurl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh\n```\n\n## Usage\n\n### Running the Server\n\n#### Using uv:\n\n```bash\nuv run python -m arduino_mcp.server\n```\n\n#### Using FastMCP CLI:\n\n```bash\nuv run fastmcp run arduino_mcp/server.py:mcp\n```\n\n#### For HTTP transport:\n\n```bash\nuv run fastmcp run arduino_mcp/server.py:mcp --transport http --port 8000\n```\n\n### Configuration for MCP Clients\n\n#### For Cursor IDE\n\nThe project includes `.cursor/mcp.json` configuration. Cursor will automatically detect it when you open the project.\n\nAlternatively, add to your global Cursor settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"arduino\": {\n      \"command\": \"uvx\",\n      \"args\": [\"arduino-mcp\"]\n    }\n  }\n}\n```\n\n#### For Claude Desktop\n\nAdd to your MCP configuration file:\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`  \n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"arduino\": {\n      \"command\": \"uvx\",\n      \"args\": [\"arduino-mcp\"]\n    }\n  }\n}\n```\n\n## Testing\n\nTo verify the Arduino MCP server is working:\n\n```bash\n# Test import\nuv run python -c \"from arduino_mcp import mcp; print('Server imports successfully')\"\n\n# Start the server\nuv run fastmcp run arduino_mcp/server.py:mcp\n```\n\nOnce running in Cursor IDE, you can test the tools directly in the chat interface.\n\n## Example Workflows\n\n### 1. Project-Based Workflow with Board Attach (Recommended)\n\n```python\n# Find your connected board\nlist_connected_boards()\n\n# Create a new sketch\ncreate_new_sketch(\"MyProject\")\n\n# Attach board settings to sketch (IDE-like experience!)\narduino_cli_command(\"board attach -p COM3 -b arduino:avr:uno MyProject\")\n\n# This creates sketch.yaml with your board settings\n\n# Now compile and upload without repeating FQBN/port\ncompile_sketch(\"MyProject\", \"\")  # Reads from sketch.yaml\nupload_sketch(\"MyProject\", \"\", \"\")  # Reads from sketch.yaml\n\n# Monitor serial output with bidirectional communication\nserial_monitor(\n    port=\"COM3\",\n    baudrate=115200,\n    duration=30,\n    send_commands=\"LED ON\\nLED OFF\",  # Send commands to device\n    save_to_file=\"output.log\"  # Save buffer to file\n)\n```\n\n**Why use board attach?**\n\n- Settings persist per-sketch (not globally)\n- No need to repeat FQBN and port every time\n- Team-friendly (sketch.yaml can be version controlled)\n- Works exactly like Arduino IDE 2.x\n\n### 2. Basic Setup and Blink LED\n\n```python\n# Check if Arduino CLI is installed\ncheck_arduino_cli_installed()\n\n# Find connected Arduino boards\nlist_connected_boards()\nfind_arduino_ports()\nget_best_port()\n\n# Create a new sketch\ncreate_new_sketch(\"BlinkLED\", \"./sketches\")\n\n# Use the blink_led_example prompt for code template\n\n# Compile the sketch\ncompile_sketch(\"./sketches/BlinkLED\", \"arduino:avr:uno\")\n\n# Upload to board\nupload_sketch(\"./sketches/BlinkLED\", \"arduino:avr:uno\", \"COM3\")\n```\n\n### 2. Basic Setup and Blink LED\n\n```python\n# Check if Arduino CLI is installed\narduino_cli_command(\"version\")\n\n# Find connected Arduino boards\nlist_connected_boards()\nlist_ports(arduino_only=True)\n\n# Create a new sketch\ncreate_new_sketch(\"BlinkLED\", \"./sketches\")\n\n# Use the blink_led_example prompt for code template\n\n# Compile the sketch\ncompile_sketch(\"./sketches/BlinkLED\", \"arduino:avr:uno\")\n\n# Upload to board\nupload_sketch(\"./sketches/BlinkLED\", \"arduino:avr:uno\", \"COM3\")\n\n# Monitor output\nserial_monitor(\"COM3\", baudrate=115200, duration=20)\n```\n\n### 3. Library Installation and Usage\n\n```python\n# Search for a library\nsearch_libraries(\"Adafruit SSD1306\")\n\n# Install the library\ninstall_library(\"Adafruit SSD1306\")\n\n# List installed libraries\nlist_installed_libraries()\n```\n\n### 4. Enhanced Serial Monitor Features\n\n```python\n# Basic monitoring (115200 is now the default)\nserial_monitor(\"COM3\", duration=30)\n\n# Send commands while monitoring (bidirectional)\nserial_monitor(\n    port=\"COM3\",\n    baudrate=115200,\n    duration=30,\n    send_commands=\"GET_STATUS\\nSET_LED 1\"\n)\n\n# Save buffer to file for analysis\nserial_monitor(\n    port=\"COM3\",\n    baudrate=115200,\n    duration=60,\n    save_to_file=\"sensor_data.log\"\n)\n\n# Combined: send commands and save output\nserial_monitor(\n    port=\"COM3\",\n    baudrate=115200,\n    duration=45,\n    send_commands=\"START_LOGGING\",\n    save_to_file=\"experiment_results.txt\"\n)\n```\n\n**Buffer Features:**\n\n- Circular buffer (10MB default, configurable via env var)\n- Memory-safe (won't crash on long-running captures)\n- Thread-safe operation\n- Automatic statistics (lines captured, buffer usage)\n\n### 5. Image to C Array Conversion\n\n```python\n# Check ImageMagick installation\ncheck_imagemagick_installed()\n\n# Convert image to C array for Arduino displays\nconvert_image_to_c_array(\n    \"logo.png\",\n    width=128,\n    height=64,\n    var_name=\"logo_bitmap\",\n    output_file=\"logo.h\"\n)\n```\n\n### 6. Resource Access\n\n```python\n# Read a sketch file\nread_resource(\"sketch://./BlinkLED/BlinkLED.ino\")\n\n# Get Arduino configuration\nread_resource(\"arduino-config://main\")\n\n# Get board details\nread_resource(\"board-info://arduino:avr:uno\")\n```\n\n## Tools Reference\n\n### Board \u0026 Port Detection\n\n- `check_arduino_cli_installed()` - Verify Arduino CLI installation\n- `list_connected_boards()` - List all connected Arduino boards\n- `list_serial_ports()` - List all serial ports\n- `find_arduino_ports()` - Find Arduino-specific ports\n- `get_best_port()` - Auto-detect best port candidate\n- `verify_port(port)` - Verify if a port is accessible\n\n### Core Management\n\n- `list_installed_cores()` - List installed Arduino cores\n- `search_cores(query)` - Search for Arduino cores\n- `install_core(core)` - Install an Arduino core\n\n### Library Management\n\n- `search_libraries(query)` - Search for Arduino libraries\n- `install_library(library)` - Install an Arduino library\n- `list_installed_libraries()` - List installed libraries\n\n### Sketch Operations\n\n- `create_new_sketch(name, path)` - Create a new Arduino sketch\n- `compile_sketch(path, fqbn)` - Compile an Arduino sketch\n- `upload_sketch(path, fqbn, port)` - Upload sketch to board\n\n### Utilities\n\n- `get_arduino_help(command)` - Get help for Arduino CLI commands\n- `initialize_config()` - Initialize Arduino CLI configuration\n- `clean_cache()` - Clean Arduino CLI cache\n- `check_imagemagick_installed()` - Check ImageMagick installation\n- `convert_image_to_c_array(...)` - Convert images to C arrays\n\n## Common FQBNs\n\n- Arduino Uno: `arduino:avr:uno`\n- Arduino Mega 2560: `arduino:avr:mega`\n- Arduino Nano: `arduino:avr:nano`\n- Arduino Leonardo: `arduino:avr:leonardo`\n- ESP32: `esp32:esp32:esp32`\n- ESP8266: `esp8266:esp8266:generic`\n\n## Architecture\n\n```\narduino-mcp/\n├── arduino_mcp/\n│   ├── __init__.py          # Package initialization\n│   ├── server.py            # Main MCP server with tools, resources, prompts\n│   ├── cli_wrapper.py       # Arduino CLI wrapper\n│   ├── port_detector.py     # Serial port detection utilities\n│   ├── image_converter.py   # ImageMagick image conversion\n│   └── platform_utils.py    # Cross-platform OS detection \u0026 handling\n├── pyproject.toml           # Project configuration\n└── README.md               # This file\n```\n\n### Cross-Platform Design\n\n- **platform_utils.py**: Centralized OS detection and platform-specific behavior\n- **Automatic detection**: Windows (COM*), macOS (/dev/tty.*), Linux (/dev/ttyUSB*, /dev/ttyACM*)\n- **Serial keywords**: Platform-specific Arduino device identification\n- **Error handling**: PermissionError for Linux, graceful fallbacks\n- **Path handling**: OS-appropriate path separators and formats\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\n## References\n\n- [FastMCP Documentation](https://gofastmcp.com/)\n- [Arduino CLI Documentation](https://arduino.github.io/arduino-cli/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [FastMCP Tools](https://gofastmcp.com/servers/tools)\n- [FastMCP Resources](https://gofastmcp.com/servers/resources)\n- [FastMCP Prompts](https://gofastmcp.com/servers/prompts)\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Farduino-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniradler%2Farduino-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Farduino-mcp/lists"}