Arduino MCP Server

arduino-mcp-server

通过自然语言，让 AI 助手全面控制 Arduino——编译、上传、监控串口，并验证接线安全性。

它是 HardwareMCP 生态系统的一部分，该生态系统包含连接 AI 与实体硬件的开源 MCP 服务。

---

功能介绍

AI 助手可以控制 Jira、GitHub 和数据库，却无法与微控制器通信——现在这一切成为可能。

arduino-mcp-server 将 arduino-cli 封装为 MCP 服务，让 AI 能够：

• 自动检测已连接的开发板和端口
• 编译并上传草图，无需操作终端
• 监控串口输出，并通过有状态会话进行操作（打开、读取、等待、写入、关闭）
• 运行电气安全检查，再向硬件发送命令
• 管理依赖项——核心包、库和 CLI 安装

---

快速开始

安装：

npm install -g arduino-mcp-server

添加到 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "arduino": {
      "command": "npx",
      "args": ["-y", "arduino-mcp-server"],
      "env": {
        "ARDUINO_CLI_PATH": "arduino-cli",
        "ARDUINO_SKETCH_ROOT": "/path/to/your/sketches"
      }
    }
  }
}

需要在 PATH 中安装 arduino-cli，也可以让此服务为你安装。

---

你可以这样说

从头开始配置：

“检查是否已安装 Arduino CLI，并为 Arduino Uno 完成所有设置。”

编译并上传：

“编译我的 Blink 草图，并将它上传到 COM6 上的 Uno。”

串口监控：

“在 COM6 上以 115200 波特率打开串口，并等待设备打印 READY。”

安全优先的工作流：

“在我发送命令前，先对一个引脚 13 接入 5V、25mA 的 Arduino Uno 执行安全预检。”

---

工具

工具	功能
arduino_cli_doctor	检查 Arduino CLI 的安装情况和版本
install_arduino_cli	指引完成 arduino-cli 安装
detect_hardware	检测已连接的开发板并推断 FQBN
list_connected_boards	列出所有已连接的 Arduino 开发板
list_serial_ports	列出可用串口
ensure_core_installed	检查／安装开发板核心包
compile_sketch	为目标开发板编译草图
upload_sketch	将已编译的草图上传到开发板
upload_and_wait_ready	上传并等待设备就绪信号
serial_open_session	打开有状态的串口会话
serial_read	读取缓冲的串口数据
serial_expect	等待串口输出中出现指定模式
serial_write	通过串口发送数据
serial_close_session	关闭串口会话
serial_list_sessions	列出活动的串口会话
read_serial_snapshot	快速读取一次串口数据
safety_preflight	执行硬件操作前的电气安全检查
get_board_details	获取开发板的引脚／功能详情
list_supported_boards	列出 arduino-cli 支持的所有开发板
list_board_reference	浏览开发板引脚参考资料
search_board_reference	按关键词搜索开发板参考资料

资源：

• arduino://boards/reference — 结构化的开发板引脚／功能参考资料

提示词：

• arduino-cli-bootstrap-policy — arduino-cli 设置行为策略
• arduino-setup-assistant — 引导完成 Arduino 环境设置

---

安全预检防护措施

safety_preflight（以及传递给 upload_sketch、upload_and_wait_ready 和 serial_write 的 safetyContext）现在还会检查电池和 ESP32 系列引脚的常见隐患。检查由小型且易于扩展的数据表驱动，不会硬编码为仅适用于某一块开发板：

电池充电倍率（C-rate）检查 — 传入 battery 对象（包含 capacityMah、chargeCurrentMa、chemistry），检查会计算 chargeCurrentMa / batteryCapacityMah 并根据结果发出提示：

• 高于 1C 时，发出 BATTERY_CRATE_UNSAFE（严重，阻止操作）
• 高于 0.5C 时，发出 BATTERY_CRATE_CAUTION（轻微，不阻止操作）

常见的小型 LiPo 电芯的安全充电电流额定值通常约为 0.5–1C，因此提示会详细说明计算过程，例如 “向 100mAh 电芯充入 380mA，充电倍率为 3.8C，远高于典型小型 LiPo 电芯约 0.5-1C 的安全范围；继续操作前，请核实电芯实际的额定充电电流。” 如果省略 chargeCurrentMa，系统会根据小型开发板 → 板载充电 IC 查找表推断该值（目前已收录 Seeed XIAO ESP32S3、XIAO ESP32S3 Sense 和 XIAO ESP32C3；参见 data/battery-charge-ic-reference.json，可轻松添加更多开发板）。这些数值是制造商公布的近似值——在生产工作流中采用前，请对照适用于确切开发板修订版本的最新数据手册或 Wiki 核实。

电池极性确认 — 当 battery.connecting: true（或设置了任何电池字段），但 battery.polarityConfirmed 未明确设为 true 时，预检会通过 BATTERY_POLARITY_UNCONFIRMED 阻止操作，并提醒不要根据导线颜色推断 BAT+/BAT-。对于 Seeed XIAO 开发板，提示会注明官方规范：负极焊盘距离 USB-C 端口最近，正极焊盘距离最远。

ESP32 系列引脚安全（通过 data/board-reference.json 按开发板配置数据）：

• SPI 闪存引脚（经典 ESP32 WROOM/WROVER 模块上的 GPIO6-11）— 严重错误（SPI_FLASH_PIN_USED）；连接这些引脚会导致无法启动。
• 启动绑带引脚（经典 ESP32 上的 GPIO0/2/12/15）— 警告；运行时可用，但如果在启动或复位期间被外部电路拉住，则存在风险（现有检查）。
• 无内部上拉电阻的仅输入引脚（经典 ESP32 上的 GPIO34-39）— 警告（NO_INTERNAL_PULL_PIN）；将这些引脚用作按钮或开关时，请添加外部上拉或下拉电阻。
• Seeed XIAO ESP32S3 — 将其 11 个可用 GPIO（D0-D10）及默认 I2C 引脚 D4/D5 纳入数据模型；每当 D6/D7 接线时，都会显示一条提示信息：它们默认是硬件 UART1 TX/RX，但启用“USB CDC on Boot”后，就能作为普通 GPIO 使用。

以上所有开发板数据均存储在 JSON 中，并以开发板 ID/FQBN 为键，因此无需修改防护逻辑即可添加更多开发板。

---

配置

变量	默认值	说明
ARDUINO_CLI_PATH	arduino-cli	arduino-cli 二进制文件的路径
ARDUINO_SKETCH_ROOT	(无)	将草图路径限制在此目录中

---

开发

git clone https://github.com/hardware-mcp/arduino-mcp-server
cd arduino-mcp-server
npm install
npm run typecheck
npm test
npm run build
npm run dev

---

属于 HardwareMCP

此服务属于 HardwareMCP 生态系统 — 该生态系统由一系列 MCP 服务组成，可让 AI 助手真正控制物理硬件。

---

许可证

MIT — 参见 LICENSE。

支持

提交问题