MCP Arduino Server (mcp-arduino-server)

MCP Arduino Server (mcp-arduino-server)

这是一个由 FastMCP 驱动的桥接工具，通过模型上下文协议（MCP）提供 arduino-cli 功能。可管理草图、开发板、库和文件，还能根据 YAML 或自然语言生成 WireViz 原理图。

要求

• Python ≥3.10
• PATH 中的 arduino-cli
• MCP SDK（mcp[cli]）
• WireViz（可选；用于生成图表）
• OPENAI_API_KEY（用于 AI 驱动的 WireViz）
• thefuzz[speedup]（可选；启用本地模糊库搜索）

安装

从 PyPI 安装：

pip install mcp-arduino-server

从源代码安装：

git clone https://github.com/Volt23/mcp-arduino-server.git
cd mcp-arduino-server
pip install .

配置

环境变量会覆盖默认值：

变量	默认值／说明
ARDUINO_CLI_PATH	自动检测
WIREVIZ_PATH	自动检测
MCP_SKETCH_DIR	~/Documents/Arduino_MCP_Sketches/
LOG_LEVEL	INFO
OPENAI_API_KEY	你的 OpenAI API 密钥（AI 驱动的 WireViz 必需）
OPENROUTER_API_KEY	OPENAI_API_KEY 的可选替代项
ARDUINO_SERIAL_LOG_MAX_BYTES	每个串行日志文件的最大大小（字节；0 表示禁用）
ARDUINO_SERIAL_LOG_ROTATE_COUNT	要保留的轮转串行日志数量

快速开始

mcp-arduino-server

服务通过 STDIO 接收 JSON-RPC MCP 调用。主要方法：

草图

• create_new_sketch(name)
• list_sketches()
• read_file(path)
• write_file(path, content[, board_fqbn]) (自动编译并打开 .ino)

构建与部署

• verify_code(sketch, board_fqbn)
• upload_sketch(sketch, port, board_fqbn)

库

• lib_search(name[, limit])
• lib_install(name)
• list_library_examples(name)

开发板

• list_boards()
• board_search(query)

串行监视器

• serial_monitor_start(port, baud, buffer_lines, log_to_file, ...)
• serial_monitor_read(monitor_id, lines)
• serial_monitor_list()
• serial_monitor_stop(monitor_id)

文件操作

• rename_file(src, dest)
• remove_file(path) (具有破坏性；操作限制在主目录和草图目录内)

WireViz 图表

• generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit") (由 AI 驱动；需要 OPENAI_API_KEY，并会自动打开 PNG)

MCP 客户端配置

要集成 MCP 客户端（例如 Claude Desktop），请在环境中设置 OpenAI API 密钥（也可使用 OPENROUTER_API_KEY 代替，以连接 OpenRouter）：

{
  "mcpServers": {
    "arduino": {
      "command": "/path/to/mcp-arduino-server",
      "args": [],
      "env": {
        "WIREVIZ_PATH": "/path/to/wireviz",
        "OPENAI_API_KEY": "<your-openai-api-key>"
      }
    }
  }
}

故障排除

• 设置 LOG_LEVEL=DEBUG 以输出详细日志。
• 检查文件和串行端口的权限。
• 安装缺少的核心：arduino-cli core install <spec>。
• 手动运行 arduino-cli 命令进行调试。

许可证

MIT