MCP Arduino Server

MCP Arduino Server (mcp-arduino-server)

Uma ponte baseada em FastMCP que expõe funcionalidades do arduino-cli por meio do Model Context Protocol (MCP). Gerencie sketches, placas, bibliotecas, arquivos e gere esquemas WireViz a partir de YAML ou linguagem natural.

Requisitos

• Python ≥3.10
• arduino-cli no PATH
• MCP SDK (mcp[cli])
• WireViz (opcional; para geração de diagramas)
• OPENAI_API_KEY (para WireViz com IA)
• thefuzz[speedup] (opcional; habilita busca difusa local de bibliotecas)

Instalação

Via PyPI:

pip install mcp-arduino-server

A partir do código-fonte:

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

Configuração

Variáveis de ambiente substituem os padrões:

Variável	Padrão / Descrição
ARDUINO_CLI_PATH	detectado automaticamente
WIREVIZ_PATH	detectado automaticamente
MCP_SKETCH_DIR	~/Documents/Arduino_MCP_Sketches/
LOG_LEVEL	INFO
OPENAI_API_KEY	sua chave da API OpenAI (necessária para WireViz com IA)
OPENROUTER_API_KEY	alternativa opcional ao OPENAI_API_KEY
ARDUINO_SERIAL_LOG_MAX_BYTES	tamanho máximo por arquivo de log serial (bytes; 0 desativa)
ARDUINO_SERIAL_LOG_ROTATE_COUNT	número de logs seriais rotacionados a manter

Início Rápido

mcp-arduino-server

O servidor escuta em STDIO por chamadas JSON-RPC MCP. Métodos principais:

Sketches

• create_new_sketch(name)
• list_sketches()
• read_file(path)
• write_file(path, content[, board_fqbn]) (compila automaticamente e abre o .ino)

Build e Deploy

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

Bibliotecas

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

Placas

• list_boards()
• board_search(query)

Monitor Serial

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

Operações de Arquivo

• rename_file(src, dest)
• remove_file(path) (destrutivo; operações restritas aos diretórios home e de sketches)

Diagramas WireViz

• generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit") (com IA; requer OPENAI_API_KEY, abre PNG automaticamente)

Configuração do Cliente MCP

Para integrar com clientes MCP (ex.: Claude Desktop), defina sua chave da API OpenAI no ambiente (ou alternativamente OPENROUTER_API_KEY para OpenRouter):

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

Solução de Problemas

• Defina LOG_LEVEL=DEBUG para logs detalhados.
• Verifique permissões de arquivos e portas seriais.
• Instale núcleos ausentes: arduino-cli core install <spec>.
• Execute comandos arduino-cli manualmente para depurar.

Licença

MIT