使用说明

Arduino MCP服务器

全面的模型上下文协议（MCP） Arduino CLI交互服务器，使用 FastMCP此服务器使AI代理能够与Arduino CLI无缝交互，用于开发、调试、代码验证等。

特性

🛠️ 工具（所有3个MCP支柱）

CLI管理：检查安装，获取命令帮助
电路板检测：列出连接的板，查找Arduino端口，自动检测最佳端口
核心管理层：搜索、安装和列出Arduino内核
图书馆管理：搜索、安装和列出Arduino库
草图操作：创建、编译和上传草图
增强型串行监视器：双向通信、缓冲、文件导出
图像转换：将图像转换为C数组以用于显示应用程序（需要ImageMagick）
配置：初始化配置，清理缓存

📚 资源

sketch://{path} -读取Arduino草图文件（.ino、.cpp、.h）
arduino-config://main -访问Arduino CLI配置
board-info://{fqbn} -获取详细的董事会信息

💡 提示词

闪烁LED示例：基本LED闪烁草图模板
传感器读数示例：模拟传感器读取模板
绘制项目工作流程：类似IDE的板连接体验
完整开发工作流程：完整的Arduino开发指南
故障排除指南：常见问题和解决方案

🚀 高级功能

日志记录：全面的日志记录，包括信息、警告、错误级别(来源)
进度报告：长时间操作的实时进度更新(来源)
上下文集成：完全支持MCP上下文以增强交互(来源)
注释：用于更好用户体验的适当工具注释（只读、破坏性、openWorld提示）

先决条件

Python 3.10+
紫外线（Python包管理器）
Arduino命令行界面
ImageMagick （可选，用于图像转换）

环境变量

使用以下可选环境变量自定义服务器行为：

变量	默认值	描述
`ARDUINO_CLI_PATH`	`arduino-cli`	Arduino CLI可执行文件的路径
`MCP_SKETCH_DIR`	特定于操作系统的*	覆盖默认草图目录
`ARDUINO_SERIAL_BUFFER_SIZE`	`10`	串行缓冲区大小（MB）
`ARDUINO_CONFIG_FILE`	自动检测	自定义Arduino CLI配置文件路径

*默认草图目录：

窗户： %DOCUMENTS%\Arduino
macOS： ~/Documents/Arduino
Linux： ~/Arduino

安装

克隆此存储库：

git clone <your-repo-url>
cd arduino-mcp

使用uv安装依赖项：

uv sync

安装Arduino命令行界面：

# Windows (using winget)
winget install ArduinoSA.CLI

# macOS
brew install arduino-cli

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

用法

运行服务器

使用紫外线：

uv run python -m arduino_mcp.server

使用FastMCP CLI：

uv run fastmcp run arduino_mcp/server.py:mcp

对于HTTP传输：

uv run fastmcp run arduino_mcp/server.py:mcp --transport http --port 8000

MCP客户端的配置

用于游标IDE

该项目包括 .cursor/mcp.json 配置。当您打开项目时，游标会自动检测到它。

或者，添加到全局光标设置中：

{
  "mcpServers": {
    "arduino": {
      "command": "uvx",
      "args": ["arduino-mcp"]
    }
  }
}

适用于克劳德桌面

添加到MCP配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "arduino": {
      "command": "uvx",
      "args": ["arduino-mcp"]
    }
  }
}

测试

要验证Arduino MCP服务器是否正常工作：

# Test import
uv run python -c "from arduino_mcp import mcp; print('Server imports successfully')"

# Start the server
uv run fastmcp run arduino_mcp/server.py:mcp

在Cursor IDE中运行后，您可以直接在聊天界面中测试这些工具。

示例工作流

1.带Board Attach的基于项目的工作流（推荐）

# Find your connected board
list_connected_boards()

# Create a new sketch
create_new_sketch("MyProject")

# Attach board settings to sketch (IDE-like experience!)
arduino_cli_command("board attach -p COM3 -b arduino:avr:uno MyProject")

# This creates sketch.yaml with your board settings

# Now compile and upload without repeating FQBN/port
compile_sketch("MyProject", "")  # Reads from sketch.yaml
upload_sketch("MyProject", "", "")  # Reads from sketch.yaml

# Monitor serial output with bidirectional communication
serial_monitor(
    port="COM3",
    baudrate=115200,
    duration=30,
    send_commands="LED ON\nLED OFF",  # Send commands to device
    save_to_file="output.log"  # Save buffer to file
)

为什么要使用板连接？

每个草图的设置都保持不变（不是全局）
无需每次重复FQBN和端口
团队友好（sketch.yaml可以进行版本控制）
工作原理与Arduino IDE 2.x完全相同

2.基本设置和闪烁LED

# Check if Arduino CLI is installed
check_arduino_cli_installed()

# Find connected Arduino boards
list_connected_boards()
find_arduino_ports()
get_best_port()

# Create a new sketch
create_new_sketch("BlinkLED", "./sketches")

# Use the blink_led_example prompt for code template

# Compile the sketch
compile_sketch("./sketches/BlinkLED", "arduino:avr:uno")

# Upload to board
upload_sketch("./sketches/BlinkLED", "arduino:avr:uno", "COM3")

2.基本设置和闪烁LED

# Check if Arduino CLI is installed
arduino_cli_command("version")

# Find connected Arduino boards
list_connected_boards()
list_ports(arduino_only=True)

# Create a new sketch
create_new_sketch("BlinkLED", "./sketches")

# Use the blink_led_example prompt for code template

# Compile the sketch
compile_sketch("./sketches/BlinkLED", "arduino:avr:uno")

# Upload to board
upload_sketch("./sketches/BlinkLED", "arduino:avr:uno", "COM3")

# Monitor output
serial_monitor("COM3", baudrate=115200, duration=20)

3.图书馆的安装和使用

# Search for a library
search_libraries("Adafruit SSD1306")

# Install the library
install_library("Adafruit SSD1306")

# List installed libraries
list_installed_libraries()

4.增强的串行监视器功能

# Basic monitoring (115200 is now the default)
serial_monitor("COM3", duration=30)

# Send commands while monitoring (bidirectional)
serial_monitor(
    port="COM3",
    baudrate=115200,
    duration=30,
    send_commands="GET_STATUS\nSET_LED 1"
)

# Save buffer to file for analysis
serial_monitor(
    port="COM3",
    baudrate=115200,
    duration=60,
    save_to_file="sensor_data.log"
)

# Combined: send commands and save output
serial_monitor(
    port="COM3",
    baudrate=115200,
    duration=45,
    send_commands="START_LOGGING",
    save_to_file="experiment_results.txt"
)

缓冲器特性：

循环缓冲区（默认10MB，可通过env-var配置）
内存安全（在长时间运行的捕获时不会崩溃）
线程安全操作
自动统计（捕获的行数、缓冲区使用情况）

5.图像到C数组的转换

# Check ImageMagick installation
check_imagemagick_installed()

# Convert image to C array for Arduino displays
convert_image_to_c_array(
    "logo.png",
    width=128,
    height=64,
    var_name="logo_bitmap",
    output_file="logo.h"
)

6.资源访问

# Read a sketch file
read_resource("sketch://./BlinkLED/BlinkLED.ino")

# Get Arduino configuration
read_resource("arduino-config://main")

# Get board details
read_resource("board-info://arduino:avr:uno")

工具参考

板和端口检测

check_arduino_cli_installed() -验证Arduino CLI安装
list_connected_boards() -列出所有连接的Arduino板
list_serial_ports() -列出所有串行端口
find_arduino_ports() -查找Arduino特定端口
get_best_port() -自动检测最佳端口候选
verify_port(port) -验证端口是否可访问

核心管理层

list_installed_cores() -列出已安装的Arduino内核
search_cores(query) -搜索Arduino内核
install_core(core) -安装Arduino内核

图书馆管理

search_libraries(query) -搜索Arduino库
install_library(library) -安装Arduino库
list_installed_libraries() -列出已安装的库

草图操作

create_new_sketch(name, path) -创建新的Arduino草图
compile_sketch(path, fqbn) -编译Arduino草图
upload_sketch(path, fqbn, port) -将草图上传到板上

公用事业

get_arduino_help(command) -获取Arduino CLI命令的帮助
initialize_config() -初始化Arduino CLI配置
clean_cache() -清理Arduino CLI缓存
check_imagemagick_installed() -检查ImageMagick安装
convert_image_to_c_array(...) -将图像转换为C数组

常见FQBN

Arduino Uno： arduino:avr:uno
Arduino Mega 2560： arduino:avr:mega
Arduino Nano： arduino:avr:nano
Arduino莱昂纳多： arduino:avr:leonardo
尤其是32： esp32:esp32:esp32
尤其是8266： esp8266:esp8266:generic

建筑

arduino-mcp/
├── arduino_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server with tools, resources, prompts
│   ├── cli_wrapper.py       # Arduino CLI wrapper
│   ├── port_detector.py     # Serial port detection utilities
│   ├── image_converter.py   # ImageMagick image conversion
│   └── platform_utils.py    # Cross-platform OS detection & handling
├── pyproject.toml           # Project configuration
└── README.md               # This file

跨平台设计

platform_utils.py：集中式操作系统检测和特定于平台的行为
自动检测：Windows（COM*）、macOS（/dev/tty）。)，Linux（/dev/ttyUSB），/dev/ttyACM*）
序列关键字：特定于平台的Arduino设备标识
错误处理：Linux权限错误，优雅的回退
路径处理：操作系统适当的路径分隔符和格式

Arduino CLI 交互服务器

使用说明

Arduino MCP服务器

特性

🛠️ 工具（所有3个MCP支柱）

📚 资源

💡 提示词

🚀 高级功能

先决条件

环境变量

安装

用法

运行服务器

使用紫外线：

使用FastMCP CLI：

对于HTTP传输：

MCP客户端的配置

用于游标IDE

适用于克劳德桌面

测试

示例工作流

1.带Board Attach的基于项目的工作流（推荐）

2.基本设置和闪烁LED

2.基本设置和闪烁LED

3.图书馆的安装和使用

4.增强的串行监视器功能

5.图像到C数组的转换

6.资源访问

工具参考

板和端口检测

核心管理层

图书馆管理

草图操作

公用事业

常见FQBN

建筑

跨平台设计

贡献

参考文献

许可证

使用说明

Arduino MCP服务器

特性

🛠️ 工具 （所有3个MCP支柱）

📚 资源

💡 提示词

🚀 高级功能

先决条件

环境变量

安装

用法

运行服务器

使用紫外线：

使用FastMCP CLI：

对于HTTP传输：

MCP客户端的配置

用于游标IDE

适用于克劳德桌面

测试

示例工作流

1.带Board Attach的基于项目的工作流（推荐）

2.基本设置和闪烁LED

2.基本设置和闪烁LED

3.图书馆的安装和使用

4.增强的串行监视器功能

5.图像到C数组的转换

6.资源访问

工具参考

板和端口检测

核心管理层

图书馆管理

草图操作

公用事业

常见FQBN

建筑

跨平台设计

贡献

参考文献

许可证

相关 MCP

代码验证工具

AI代码工作流管理工具

Flowbite组件生成服务

LLM辩证推理工具

代码验证工具

Ross脚本处理工具

🛠️ 工具（所有3个MCP支柱）