MCP Arduino Server

MCP Arduino Server (mcp-arduino-server)

Un puente impulsado por FastMCP que expone la funcionalidad de arduino-cli a través del Model Context Protocol (MCP). Gestiona bocetos, placas, bibliotecas, archivos, y genera esquemas WireViz desde YAML o lenguaje natural.

Requisitos

• Python ≥3.10
• arduino-cli en PATH
• MCP SDK (mcp[cli])
• WireViz (opcional; para generación de diagramas)
• OPENAI_API_KEY (para WireViz con IA)
• thefuzz[speedup] (opcional; habilita búsqueda difusa de bibliotecas locales)

Instalación

Desde PyPI:

pip install mcp-arduino-server

Desde el código fuente:

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

Configuración

Las variables de entorno anulan los valores predeterminados:

Variable	Descripción predeterminada / Descripción
ARDUINO_CLI_PATH	auto-detectado
WIREVIZ_PATH	auto-detectado
MCP_SKETCH_DIR	~/Documents/Arduino_MCP_Sketches/
LOG_LEVEL	INFO
OPENAI_API_KEY	tu clave de API de OpenAI (requerida para WireViz con IA)
OPENROUTER_API_KEY	alternativa opcional a OPENAI_API_KEY
ARDUINO_SERIAL_LOG_MAX_BYTES	tamaño máximo por archivo de registro serial (bytes; 0 desactiva)
ARDUINO_SERIAL_LOG_ROTATE_COUNT	número de registros seriales rotados a conservar

Inicio rápido

mcp-arduino-server

El servidor escucha en STDIO para llamadas MCP JSON-RPC. Métodos clave:

Bocetos

• create_new_sketch(name)
• list_sketches()
• read_file(path)
• write_file(path, content[, board_fqbn]) (compila automáticamente y abre .ino)

Compilar y desplegar

• 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 serie

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

Operaciones de archivo

• rename_file(src, dest)
• remove_file(path) (destructivo; operaciones limitadas a los directorios de inicio y de bocetos)

Diagramas WireViz

• generate_circuit_diagram_from_description(desc, sketch="", output_base="circuit") (con IA; requiere OPENAI_API_KEY, abre PNG automáticamente)

Configuración del cliente MCP

Para integrarse con clientes MCP (por ejemplo, Claude Desktop), establece tu clave de API de OpenAI en el entorno (o 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>"
      }
    }
  }
}

Solución de problemas

• Establece LOG_LEVEL=DEBUG para registros detallados.
• Verifica los permisos de archivos y puertos serie.
• Instala los núcleos faltantes: arduino-cli core install <spec>.
• Ejecuta comandos arduino-cli manualmente para depurar.

Licencia

MIT