JinDaGe - mcp-arduino-server MCP Details

article

README

🚀 MCP Arduino 服务器（mcp-arduino-server）

这是一个基于 FastMCP 的桥梁工具，借助 Model Context Protocol (MCP) 来暴露 arduino-cli 的功能。它能够管理代码 sketches、电路板、库文件、文件，还能从 YAML 或自然语言输入生成 WireViz 电路图。

🚀 快速开始

在命令行中输入以下命令启动服务器：

mcp-arduino-server

服务器会监听 STDIO 上的 JSON-RPC MCP 调用。关键方法如下：

Sketches（代码 sketch）

create_new_sketch(name)：创建新 sketch
list_sketches()：列出所有 sketches
read_file(path)：读取文件内容
write_file(path, content[, board_fqbn])：自动编译并打开 .ino

构建与部署

verify_code(sketch, board_fqbn)：验证代码
upload_sketch(sketch, port, board_fqbn)：上传 sketch

库文件

lib_search(name[, limit])：搜索库文件
lib_install(name)：安装库文件
list_library_examples(name)：列出库示例

电路板

list_boards()：列出所有电路板
board_search(query)：搜索电路板

文件操作

rename_file(src, dest)：重命名文件
remove_file(path)：破坏性操作，仅限于家目录及 sketch 目录

WireViz 电路图

generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit")：AI 驱动，需要 OPENAI_API_KEY，自动打开 PNG 文件

✨ 主要特性

基于 FastMCP 构建，通过 MCP 暴露 arduino-cli 功能。
可管理代码 sketches、电路板、库文件和文件。
支持从 YAML 或自然语言输入生成 WireViz 电路图。

📦 安装指南

从 PyPI 安装

pip install mcp-arduino-server

从源代码安装

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

💻 使用示例

基础用法

以下是启动服务器的基本命令：

mcp-arduino-server

高级用法

要使用 AI 驱动的 WireViz 电路图生成功能，需要设置 OPENAI_API_KEY 环境变量，然后调用相应方法：

export OPENAI_API_KEY=<your-openai-api-key>
mcp-arduino-server
# 调用生成电路图方法
generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit")

📚 详细文档

配置

环境变量可覆盖默认值，具体如下： | 变量名 | 默认值 / 描述 | |--------------------|-------------------------------------------| | ARDUINO_CLI_PATH | 自动检测 | | WIREVIZ_PATH | 自动检测 | | MCP_SKETCH_DIR | ~/Documents/Arduino_MCP_Sketches/ | | LOG_LEVEL | INFO | | OPENAI_API_KEY | 你的 OpenAI API 密钥（对 AI‑powered WireViz 必须提供）| | OPENROUTER_API_KEY | 可选的 OpenRouter API 密钥替代 OPENAI_API_KEY |

MCP 客户端配置

要与 MCP 客户端（如 Claude Desktop）集成，请在环境变量中设置 OpenAI API 密钥：

{
  "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 以启用详细日志。
检查文件和串口权限。
遇到问题时，参考项目文档或社区支持。

📄 许可证

本项目采用 MIT License。

mcp-arduino-server