AI导哈

Arduino设备控制服务器

一个通过Model Context Protocol (MCP)使用JSON-RPC 2.0控制Arduino设备的强大、安全且可扩展的服务器，适用于自动化工作流和编辑器集成。

  • by amahpour
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 amahpour/arduino-mcp-server

使用说明

Arduino MCP服务器（模型上下文协议）

一个健壮、安全和可扩展的服务器，用于通过模型上下文协议（MCP）在stdin/stdout上使用JSON-RPC 2.0控制Arduino设备。专为代理驱动的工作流、自动化以及与VSCode和Cursor等编辑器的无缝集成而设计。

目录

概述

MCP服务器提供了一个安全、可脚本化和可扩展的接口，用于编译、上传和与Arduino设备通信。它非常适合：

  • 自动设备编程
  • 代理驱动的工作流
  • 编辑器/IDE集成
  • 稳健、可测试的硬件开发

建筑

  • 语言： Python 3.10+
  • 依赖关系管理： 诗歌(pyproject.toml)
  • 项目布局：
    • src/arduino_mcp_server/ --主服务器代码（基于FastMCP）
    • sketches/ --Arduino草图示例/测试
    • tests/unit/ --快速、模拟的单元测试（无硬件）
    • tests/integration/ --依赖硬件的集成测试
  • 协议： JSON-RPC 2.0通过行分隔的stdin/stdout
  • 集装箱化： Dockerfile便于部署和USB访问
graph TD;
  Agent/Editor-->|stdin/stdout|MCP_Server["MCP Server (JSON-RPC 2.0)"];
  MCP_Server-->|serial, arduino-cli|Arduino;

安装

  1. 安装诗歌：
    curl -sSL https://install.python-poetry.org | python3 -
  2. 克隆和安装依赖关系：
    git clone <your-repo-url>
cd arduino-mcp-example
poetry install

配置

  • 基本使用不需要特殊配置。
  • 所有操作都通过JSON-RPC请求进行参数化。
  • 对于自定义板FQBN或端口，请在请求中指定。

用法

命令行界面

直接运行服务器：

poetry run arduino-mcp-server

对于JSON-RPC请求的测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "list_ports", "params": {}}' | poetry run arduino-mcp-server

VSCode/Cursor/Claude桌面集成

  1. 添加 .vscode/mcp.json:
    {
  "mcp": {
    "servers": {
      "arduino": {
        "type": "stdio",
        "command": "poetry",
        "args": ["run", "arduino-mcp-server"],
        "env": {
          "LOG_LEVEL": "INFO",
          "ARDUINO_CLI_PATH": "/usr/local/bin/arduino-cli"
        }
      }
    }
  }
}
  2. 重新启动编辑器。 MCP感知客户端将自动发现并启动服务器。

脚本编写/自动化

您可以使用Python、Node.js或任何语言将JSON-RPC请求发送到MCP服务器的stdin，并解析stdout的响应。

Python脚本示例

import subprocess
import json
req = {"jsonrpc": "2.0", "id": 1, "method": "list_ports", "params": {}}
proc = subprocess.Popen(["poetry", "run", "arduino-mcp-server"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
stdout, _ = proc.communicate(json.dumps(req) + "\n")
print(json.loads(stdout))

码头工人

在具有所有依赖项和USB权限的容器中运行MCP服务器：

docker build -t arduino-mcp-server .
docker run --rm --device=/dev/ttyACM0 --env LOG_LEVEL=INFO arduino-mcp-server
  • 对于macOS，请使用 /dev/cu.usbmodem* 作为设备。
  • 您可能需要调整设备权限或将您的用户添加到 dialout Linux上的组。

协议

  • 运输： 在stdin/stdout上以行分隔的JSON-RPC 2.0
  • 请求示例：
    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "compile",
  "params": {"sketch": "sketches/echo_serial/echo_serial.ino", "fqbn": "arduino:renesas_uno:unor4wifi"}
}
  • 响应示例：
    {
  "jsonrpc": "2.0",
  "result": {
    "version": "1.0",
    "data": {"success": true, "stdout": "...", "stderr": "..."}
  },
  "id": 1
}
  • 可用工具：
    • list_ports：列出可用串行端口
    • compile：编写草图
    • upload：上传已编译的草图
    • serial_send：通过串行发送消息并接收响应

测试

单元测试

  • 位于 tests/unit/
  • 运行方式：
    poetry run pytest tests/unit/
  • 快速，无需硬件（使用模拟）

集成测试

  • 位于 tests/integration/
  • 运行方式：
    poetry run pytest tests/integration/
  • 需要连接Arduino和真实草图

Arduino草图示例

  • sketches/blink/blink.ino：用于测试的基本LED闪烁示例

故障排除

  • 未找到诗歌： 使用上述命令进行安装
  • 未找到串行端口： 检查您的Arduino连接和权限
  • 测试失败： 确保您运行的是正确的套件（单元与集成）
  • 权限错误： 试着用 sudo 或调整串行设备的组成员资格
  • 未检测到Arduino： 检查电缆、端口和板类型
  • Docker USB问题： 使用 --device 标记并确保您的用户可以访问该设备

可扩展性

  • 通过扩展添加新操作 src/arduino_mcp_server/server.py 并向FastMCP注册
  • 将新草图添加到 sketches/ 获得更丰富的设备反馈
  • 根据需要添加更多单元/集成测试

常见问题解答

Q： 我可以将其与其他微控制器一起使用吗？ A： 是的，只要它们支持串行，并且可以通过arduino-cli或类似工具进行编程。

Q： 如何添加新的板类型？ A： 在JSON-RPC请求中指定正确的FQBN。

Q： 我可以在CI/CD中使用它吗？ A： 是的！使用Poetry、Docker和CLI自动化测试和设备编程。

Q： 我如何获得帮助或做出贡献？ A： 在存储库上打开问题或PR。

有关更高级的集成、脚本或代理驱动的工作流，请参阅中的代码和注释 src/arduino_mcp_server/server.py.

相关 MCP