mcp-serial
Allows AI agents to interact with Arduino boards over a serial connection, including listing ports, opening a port, sending commands and queries, reading responses, resetting the board, and controlling DTR/RTS lines.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-serial find my ESP32, reset it and show me the boot log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_portat 115200 →reset_device→ boot log showsGuru Meditation Error: Core 1 panic'ed (LoadProhibited)atPC: 0x400d1a2f… "That address is insideparse_packet()insrc/protocol.cpp; you dereferencebufbefore 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:
ATcommand 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 --helpClaude Code
claude mcp add serial -- uvx --from git+https://github.com/HumbertoBernal/mcp-serial mcp-serialClaude 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
Tool | What it does |
| Enumerate serial ports with USB VID/PID, manufacturer, product and serial number. |
| Open a port (baud rate, data bits, parity, stop bits, encoding) and start buffering everything it sends. |
| Release the port for other programs. |
| Byte counters, unread bytes, uptime, and the error if the device disconnected. |
| Send a command and return the reply in one call: wait for a pattern ( |
| Send text (with configurable line ending) or raw hex bytes ( |
| Consume buffered data. Waits for the first byte up to |
| Block until a substring or regex appears, return everything up to and including it. |
| Peek at the last N lines received without consuming them. |
| Drop stale buffered data. |
| Pulse DTR/RTS to reboot Arduino / ESP32 style boards and capture the boot output. |
| Drive DTR and RTS manually (bootloader entry, custom reset circuits). |
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 ] ──▶ tailTry it without hardware
pyserial URL handlers work everywhere a port name is accepted:
loop://echoes back whatever you write:open_port("loop://"), thenquery("loop://", "PING")→PING.socket://192.168.1.50:23for network serial bridges (ESP-Link, ser2net, Moxa NPort).rfc2217://host:portfor 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_TIMEOUTseconds (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 clientsDevelopment
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-serialSee 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
Available Tools
12 toolsclear_bufferA
Discard all buffered unread data on a port (line history for tail is kept).
Inputs: port (required). Returns: result
close_portA
Close a port opened with open_port and release it for other programs.
Inputs: port (required). Returns: result
list_portsC
List the serial ports currently present on this machine.
Use the description, manufacturer and vid/pid fields to identify the board
(e.g. 0x10C4:0xEA60 = CP210x on many ESP32 dev kits, 0x2341 = Arduino, 0x1A86 = CH340).
On macOS prefer the /dev/cu.* entry over /dev/tty.*.
Inputs: no named parameters. Returns: result
open_portA
Open a serial port and start buffering everything it sends.
Idempotent: opening an already-open port with the same settings just returns its status; different settings close and reopen it. The port stays open until close_port.
Inputs: port (required), parity, baudrate, bytesize, +2 more. Returns: port, error, parity, baudrate, +9 more
port_statusB
Show open ports with byte counters, buffered (unread) bytes and disconnect errors.
Inputs: port. Returns: result
queryA
Send a command and return its reply in one call. Best for request/response devices (AT modems, CLI firmware, 'PING' -> 'PONG' sketches).
Inputs: port (required), command (required), regex, expect, +4 more. Returns: sent, bytes, error, matched, +2 more
readC
Read and consume buffered data from the device (logs, sensor output, late replies).
Inputs: port (required), as_hex, max_bytes, settle_ms, +1 more. Returns: hex, text, bytes, error, +1 more
read_untilA
Wait until a pattern appears (e.g. 'OK', 'ready>', 'Temperature:') and return everything up to and including it. On timeout returns whatever arrived, with matched=false.
Inputs: port (required), pattern (required), regex, timeout_s. Returns: text, bytes, error, matched, +1 more
reset_deviceA
Reboot the board by pulsing DTR/RTS and return what it prints while booting. Only works on boards that wire those lines to reset (most USB dev boards do).
Inputs: port (required), method, wait_s. Returns: hex, text, bytes, error, +1 more
set_control_linesA
Set the DTR / RTS modem control lines manually (bootloader entry, custom reset circuits).
Inputs: port (required), dtr, rts. Returns: result
tailA
Peek at the last lines received on a port WITHOUT consuming the read buffer. Good for checking what a device has been printing while you were doing other things.
Inputs: port (required), lines. Returns: lines, partial
writeA
Send raw bytes without waiting for a reply (use query for request/response).
Inputs: data (required), port (required), as_hex, newline. Returns: bytes_written
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct serial-port operation: open/close/status/list are lifecycle, write/read/read_until/query/tail/clear_buffer handle data flow in clearly separated ways, and reset_device/set_control_lines cover control-line actions. The descriptions explicitly call out the consumption-vs-peek and reply-vs-no-reply distinctions, so an agent should not misselect.
Most tools follow verb_noun naming (open_port, list_ports, clear_buffer), but several are bare verbs (write, read, query, tail) and port_status uses a noun phrase instead of a verb. The mix is readable but not a consistent pattern.
Twelve tools is a well-scoped size for a serial-port server. Each operation has a distinct role and the count is neither bloated nor too thin.
The surface covers the full serial workflow: enumeration, open/close/status, raw write, buffered read, pattern waits, request/response queries, monitoring without consuming, buffer clearing, device reset, and manual control-line control. No major missing operation is apparent.
Maintenance
Related MCP Connectors
Connect your AI to your own devices, 3D printers, factory tools and a shared agent task pool.
Connect AI agents to discover services and coordinate real-world tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with physical serial port devices across platforms (Windows COM/Linux tty) with support for asynchronous communication, URC pattern recognition, and structured logging.1-
- AlicenseAqualityDmaintenanceEnables AI assistants to communicate with serial port devices, supporting port management, data transmission in text/binary modes, interactive terminal sessions, and automatic reconnection.1412MIT
- AlicenseAqualityDmaintenanceEnables LLMs to communicate with hardware devices via serial ports. Provides tools for listing ports, opening/closing connections, reading/writing data, and controlling serial signals.8MIT
- AlicenseAqualityCmaintenanceAllows AI agents to interact with serial devices via RS232/UART, enabling port listing, connection, read/write, control line manipulation, and protocol specification for automated debugging and testing.2778 PyPI27MIT