serial-mcp
qarnet/serial-mcp
MCP server for serial ports — non-blocking reads, DTR/RTS, streaming subscriptions, port allowlist.
Instalação
npx convez-ai qarnet/serial-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Serial MCP Server
Serial monitors are something agents can't work with well natively. serial-mcp fixes this by giving agents powerful tools for reading, writing and subscribing to serial ports.
Non-blocking reads with timeouts and pattern matching, background RX streaming, and full line control (DTR/RTS, BREAK, flow control) — so Claude, Codex, or any MCP client can flash, reset, and talk to your board without freezing the session.
MCP 2025-11-25 compliant · resource change notifications · port allowlist · stdio + HTTP transports
What It Does
Exposes serial ports as MCP tools so agents like Claude can interact with embedded devices, Arduino boards, STM32 microcontrollers, and any UART/USB-serial hardware — all through natural language.
12 tools — list_ports, list_connections, open, close, read, write, flush, set_dtr_rts, set_flow_control, send_break, subscribe, unsubscribe
3 resources — serial://ports, serial://connections, serial://connections/{id}
2 prompt templates — diagnose_port, interactive_terminal
Install
Linux
VERSION=$(curl -s https://api.github.com/repos/qarnet/serial-mcp/releases/latest | grep -oP '"tag_name": "\K[^"]+')
curl -L "https://github.com/qarnet/serial-mcp/releases/download/${VERSION}/serial-mcp-${VERSION#v}-x86_64-linux" \
-o serial-mcp && chmod +x serial-mcp && sudo mv serial-mcp /usr/local/bin/
Add user to dialout group for port access: sudo usermod -aG dialout $USER
macOS
VERSION=$(curl -s https://api.github.com/repos/qarnet/serial-mcp/releases/latest | grep -oP '"tag_name": "\K[^"]+')
ARCH=aarch64-macos # Intel: x86_64-macos
curl -L "https://github.com/qarnet/serial-mcp/releases/download/${VERSION}/serial-mcp-${VERSION#v}-${ARCH}" \
-o serial-mcp && chmod +x serial-mcp && sudo mv serial-mcp /usr/local/bin/
Windows
Download serial-mcp-{VERSION}-x86_64-windows.exe from the latest release and place it on your PATH.
Via cargo (all platforms)
cargo install serial-mcp
Via Nix
nix profile install github:qarnet/serial-mcp
Wire Up Your Agent
→ Agent configuration guide — Claude Code CLI, Claude Desktop, Cursor, VS Code, Zed, opencode, HTTP transport
{
"mcpServers": {
"serial": {
"type": "stdio",
"command": "serial-mcp",
"args": ["--allowlist=/dev/ttyACM*,/dev/ttyUSB*"]
}
}
}
Options
serial-mcp [OPTIONS]
--transport <stdio|http> Transport to use (default: stdio)
--allowlist <patterns> Comma-separated glob patterns for allowed ports
--bind <addr> HTTP bind address (default: 127.0.0.1:8000)
-h, --help Print help
RUST_LOG Log level env var (error/warn/info/debug/trace)
Transports
| Mode | How to activate | Use case |
|---|---|---|
| stdio | default | Desktop agents |
| HTTP | --transport=http | Remote / headless |
Example Agent Flow
1. list_ports → ["/dev/ttyUSB0", "/dev/ttyACM0"]
2. open(port="/dev/ttyACM0", name="board-uart", baud_rate=115200) → { connection_id: "9f...", name: "board-uart" }
3. list_connections() → [{ connection_id: "9f...", name: "board-uart", port: "/dev/ttyACM0" }]
4. set_dtr_rts(id, dtr=false, rts=false) # Arduino reset
set_dtr_rts(id, dtr=true, rts=true)
5. read(id, match={ pattern: "OK>" }, timeout_ms=3000) # pattern match in RX data
6. write(id, data="status\r\n")
7. close(id)
Development
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
# Hardware tests (requires TX-RX loopback device)
SERIAL_MCP_TEST_PORT=/dev/ttyACM0 cargo test --test hardware_loopback -- --ignored
# XIAO BLE firmware validation (requires dedicated serial-mcp test firmware)
SERIAL_MCP_XIAO_PORT=/dev/ttyACM0 cargo test --test xiao_ble_validation -- --ignored --test-threads=1
Be sure to ask your agent to give honest feedback on the tool after they finish using it. Always looking for ways to improve serial-mcp :)
Documentation
- Agent Configuration
- Testing Guide
- CHANGELOG.md
- AGENTS.md — contributor guidelines
MCP Registry
Available on the MCP Registry as:
mcp-name: io.github.qarnet/serial-mcp
License
MIT. See LICENSE.