mcp-serial

Let AI agents talk to your hardware over a serial port.

(Versión en español: README.es.md)

mcp-serial is a Model Context Protocol server that gives Claude Code, Claude Desktop, Cursor, or any MCP client a set of tools to find serial ports, open them, send commands and read what comes back: Arduino, ESP32/ESP8266, STM32, USB-UART adapters, RS-232 lab equipment, AT modems, anything that speaks UART.

Why

Debugging firmware means alt-tabbing between your editor and a serial monitor, copying stack traces around by hand. With mcp-serial the agent that is editing your code can also reset the board, read the boot log, spot the Guru Meditation Error, and go fix the line it points at, all in one conversation.

You: find my ESP32, reset it and tell me why it keeps rebooting

Agent: list_ports → /dev/cu.usbserial-0001 (CP210x, 0x10C4:0xEA60) → open_port at 115200 → reset_device → boot log shows Guru Meditation Error: Core 1 panic'ed (LoadProhibited) at PC: 0x400d1a2f … "That address is inside parse_packet() in src/protocol.cpp; you dereference buf before checking the length. Here's the fix."

Things it is good at:

• Interactive firmware debugging: reset, capture boot logs, send CLI commands, watch output.

• Bring-up of new boards: identify the port by VID/PID, try baud rates, check that the firmware answers.

• Talking to instruments and modems: AT command sets, SCPI over RS-232, custom ASCII protocols, raw hex frames.

• Sensor experiments: read a stream for a while, then let the agent summarize or plot it.

Related MCP server: UART MCP Server

Install

Requires Python 3.10+ and uv (or pipx).

# straight from GitHub (PyPI release coming)
uvx --from git+https://github.com/HumbertoBernal/mcp-serial mcp-serial --help

Claude Code

claude mcp add serial -- uvx --from git+https://github.com/HumbertoBernal/mcp-serial mcp-serial

Claude Desktop, Cursor, Windsurf, and other JSON configs

{
  "mcpServers": {
    "serial": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/HumbertoBernal/mcp-serial", "mcp-serial"]
    }
  }
}

To restrict which ports the agent may touch, add an environment variable (see Safety):

"env": { "MCP_SERIAL_ALLOWED_PORTS": "/dev/cu.usb*,/dev/ttyUSB*" }

Tools

There is also a serial://ports resource with the same information as list_ports.

Every port is read continuously by a background thread into a bounded buffer (1 MB per port) plus a 2000-line history for tail, so nothing the device prints between two tool calls is lost.

 device ──UART──▶ pyserial ──reader thread──▶ [ unread buffer ] ──▶ read / read_until / query
                                         └──▶ [ line history ] ──▶ tail

Try it without hardware

pyserial URL handlers work everywhere a port name is accepted:

• loop:// echoes back whatever you write: open_port("loop://"), then query("loop://", "PING") → PING.

• socket://192.168.1.50:23 for network serial bridges (ESP-Link, ser2net, Moxa NPort).

• rfc2217://host:port for RFC 2217 servers.

Try it with an Arduino

Flash examples/arduino_echo/arduino_echo.ino (any board, 115200 baud), then ask your agent:

open my Arduino and send it PING, TEMP? and HELP

The sketch answers PONG, a fake temperature, and a list of its commands, enough to check that the whole chain works before pointing the agent at your real firmware.

Safety

The server only moves bytes between the agent and the port. It does not flash firmware, run programs, or touch files. Still, an agent that can write arbitrary bytes to a device can trigger whatever that device's protocol allows, so:

• Allowlist ports with MCP_SERIAL_ALLOWED_PORTS (comma-separated globs, e.g. /dev/cu.usb*,COM3) or --allow GLOB (repeatable). Anything else is refused.

• Timeouts are capped at MCP_SERIAL_MAX_TIMEOUT seconds (default 120) so a tool call can never hang the agent forever; reads are capped at 1 MB.

• At most 8 ports are open at a time, and everything is closed when the server shuts down.

• Nothing is written to stdout except MCP traffic, so it is safe under stdio transport.

Flashing (esptool, avrdude) is on the roadmap as a separate, opt-in tool.

Running the server manually

mcp-serial                                  # stdio (what MCP clients spawn)
mcp-serial --allow "/dev/cu.usb*"           # restrict ports
mcp-serial --transport streamable-http --http-port 8000   # HTTP, for remote clients

Development

git clone https://github.com/HumbertoBernal/mcp-serial
cd mcp-serial
uv sync --group dev
uv run pytest          # tests use pyserial's loop:// device, no hardware needed
uv run ruff check .

Test the server interactively with the MCP inspector:

npx @modelcontextprotocol/inspector uv run mcp-serial

See ROADMAP.md for what is planned and CONTRIBUTING.md if you want to help. Issues with a hardware: label are great first contributions: test the server with a board we have not tried and report what works.

License

MIT