serial MCP server
✓ VerifiedEnables AI agents to interact with serial devices by listing ports, managing connections, and reading or writing data via RS232/UART.
Also known as es617/serial-mcp-server
- Stars
- 27
- Tools
- —
- Downloads, 30 days
- 350
- Latest version
- 0.1.3
- Last commit
- Mar 7, 2026
- License
- MIT
What is serial MCP?
serial enables AI agents to interact with serial devices by listing ports, managing connections, and reading or writing data via RS232/UART.
Summary generated from the project's README
About serial MCP server
Embedded engineers and hardware developers can interact with physical hardware by using this MCP server to bridge AI agents with serial devices. It enables conversational debugging and automated testing by allowing an agent to list available ports, manage connections, and perform data operations over RS232 or UART. The server works via stdio and is compatible with clients like Claude Code, VS Code with Copilot, and Cursor.
Beyond basic reading and writing, the server provides tools for control line manipulation, such as pulsing DTR and RTS to trigger hardware resets. It supports advanced workflows through protocol specs that teach the agent how to interpret specific byte streams and plugins that provide high-level device commands. For users on macOS or Linux, PTY mirroring allows external tools like screen or minicom to connect to the same session simultaneously. This setup transforms raw serial communication into a structured environment where an agent can reason about device behavior and automate complex firmware iteration tasks.
What you can do with it
- 1Conversational hardware debuggingAn engineer can ask an agent to connect to a microcontroller and read the boot banner to diagnose startup issues.
- 2Automated firmware testingA developer can instruct an agent to reset a device, wait for a specific prompt, and run a sequence of commands to validate output.
- 3Protocol reverse engineeringA researcher can use the agent to probe unknown command sets and infer the message formats of a new device.
- 4High-level device automationA user can create custom plugins so the agent can execute complex tasks like uploading firmware instead of sending raw bytes.
Written from the project's README. Every use case is checked against a quote from it.
How to install serial MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall serial MCP in Claude Code
$ claude mcp add serial-mcp-server -- uvx serial-mcp-serverInstall serial MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"serial-mcp-server": {
"command": "uvx",
"args": [
"serial-mcp-server"
]
}
}
}Install serial MCP in VS Code
.vscode/mcp.json
{
"servers": {
"serial-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"serial-mcp-server"
]
}
}
}Install serial MCP in VS Code CLI
$ code --add-mcp '{"name":"serial-mcp-server","type":"stdio","command":"uvx","args":["serial-mcp-server"]}'Install serial MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"serial-mcp-server": {
"command": "uvx",
"args": [
"serial-mcp-server"
]
}
}
}Install serial MCP in Codex
$ codex mcp add serial-mcp-server -- uvx serial-mcp-serverInstall serial MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.serial-mcp-server] command = "uvx" args = ["serial-mcp-server"]
Install serial MCP in Gemini CLI
$ gemini mcp add -s user serial-mcp-server uvx -- serial-mcp-serverInstall serial MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"serial-mcp-server": {
"command": "uvx",
"args": [
"serial-mcp-server"
]
}
}
}Configuration
SERIAL_MCP_MAX_CONNECTIONSMaximum simultaneous open serial connections (default 10)
SERIAL_MCP_MIRRORPTY mirror mode: 'off' (default), 'ro' (read-only), or 'rw' (read-write). macOS/Linux only.
SERIAL_MCP_MIRROR_LINKBase path for PTY symlinks (default /tmp/serial-mcp when mirror is enabled). Connections get numbered: /tmp/serial-mcp0, /tmp/serial-mcp1, etc.
SERIAL_MCP_PLUGINSPlugin policy: 'all' or comma-separated plugin names. Unset = disabled.
SERIAL_MCP_TOOL_SEPARATORTool name separator character (default '.'). Set to '_' for clients that reject dots (e.g. Cursor).
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablees617/serial-mcp-server is public and reachablegithub.com/es617/serial-mcp-server ↗Pass
- Package names this repository as its sourceserial-mcp-server names es617/serial-mcp-server as sourcepypi.org/project/serial-mcp-server/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for serial-mcp-serverpypi.org/project/serial-mcp-server/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-03-07github.com/es617/serial-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from serial-mcp-serverPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSerial MCP Server
A stateful serial port Model Context Protocol (MCP) server for developer tooling and AI agents. Works out of the box with Claude Code, VS Code with Copilot, and any MCP-compatible runtime. Communicates over stdio and uses pyserial for cross-platform serial on macOS, Windows, and Linux.
Example: Let Claude Code list available serial ports, connect to your microcontroller, reset it via DTR, and read the boot banner from your hardware.
Demo
Video walkthrough — connecting to a serial device, sending commands, reading responses, and creating plugins.
Why this exists
If you’ve ever copy-pasted commands into screen or minicom, guessed baud rates, toggled DTR to kick a bootloader, and re-run the same test sequence 20 times — this is for you.
You have a serial device. You want an AI agent to talk to it — open a port, send commands, read responses, debug protocols. This server makes that possible.
It gives any MCP-compatible agent a full set of serial tools: listing ports, opening connections, reading, writing, line-oriented I/O, control line manipulation — plus protocol specs and device plugins, so the agent can reason about higher-level device behavior instead of just raw bytes.
The agent calls these tools, gets structured JSON back, and reasons about what to do next — without you manually typing commands into a terminal for every step.
What agents can do with it:
- Develop and debug — connect to your device, send commands, read responses, and diagnose issues conversationally (boot banners, prompts, error codes).
- Iterate on new firmware — attach a protocol spec so the agent understands your command set, boot modes, and output format as they evolve.
- Automate test flows — reset device via DTR, wait for prompt, run a command sequence, validate output.
- Explore unknown devices — probe command sets, discover prompts, infer message formats.
- Build serial automation — long-running test rigs, manufacturing bring-up, CI hardware smoke tests.
Who is this for?
- Embedded engineers — faster iteration on serial protocols, conversational debugging, automated test sequences
- Hobbyists and makers — interact with serial devices without writing boilerplate; let the agent help reverse-engineer simple protocols
- QA and test engineers — build repeatable serial test suites with plugin tools
- Support and field engineers — diagnose serial device issues interactively without specialized tooling
- Researchers — automate data collection from serial devices, explore device capabilities systematically
Quickstart (Claude Code)
pip install serial-mcp-server
# Register the MCP server with Claude Code
claude mcp add serial -- serial_mcp
Then in Claude Code, try:
"List available serial ports and connect to the one on /dev/ttyUSB0 at 115200 baud."
What the agent can do
Once connected, the agent has full serial capabilities:
- List ports to find available serial devices
- Open and close connections with configurable baud rate, parity, stop bits, and encoding
- Read and write data in text, hex, or base64 format
- Line-oriented I/O — readline and read-until-delimiter for text protocols
- Control lines — set or pulse DTR and RTS for hardware reset and boot mode entry
- Flush input and output buffers
- Attach protocol specs to understand device-specific commands and data formats
- Use plugins for high-level device operations instead of raw reads/writes
- Create specs and plugins for new devices so future sessions start "knowing" your protocol
- PTY mirroring — attach screen, minicom, or custom scripts to the same serial session the agent is using
The agent can coordinate multi-step flows automatically — e.g., toggle reset, wait for prompt, send init sequence, stream output.
At a high level:
Raw Serial → Protocol Spec → Plugin
You can start with raw serial tools, then move up the stack as your device protocol becomes understood and repeatable.
Install (development)
# Editable install from repo root
pip install -e .
# Or with uv
uv pip install -e .
MCP is a protocol — this server works with any MCP-compatible client. Below are setup instructions for the most common ones.
Add to Claude Code
# Standard setup
claude mcp add serial -- serial_mcp
# Or run as a module
claude mcp add serial -- python -m serial_mcp_server
# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp
# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp
# Debug logging
claude mcp add serial -e SERIAL_MCP_LOG_LEVEL=DEBUG -- serial_mcp
Add to VS Code / Copilot
Add to your project's .vscode/mcp.json (or create it):
{
"servers": {
"serial": {
"type": "stdio",
"command": "serial_mcp",
"args": [],
"env": {
"SERIAL_MCP_PLUGINS": "all"
}
}
}
}
Adjust env to match your needs — set SERIAL_MCP_PLUGINS to specific plugin names, or add SERIAL_MCP_MIRROR for PTY mirroring.
Add to Cursor
Add to your project's .cursor/mcp.json (or create it). Cursor does not support dots in tool names, so SERIAL_MCP_TOOL_SEPARATOR must be set to _:
{
"mcpServers": {
"serial": {
"command": "serial_mcp",
"args": [],
"env": {
"SERIAL_MCP_PLUGINS": "all",
"SERIAL_MCP_TOOL_SEPARATOR": "_"
}
}
}
}
Environment variables
| Variable | Default | Description |
|---|---|---|
SERIAL_MCP_MAX_CONNECTIONS |
10 |
Maximum simultaneous open serial connections. |
SERIAL_MCP_PLUGINS |
disabled | Plugin policy: all to allow all, or name1,name2 to allow specific plugins. Unset = disabled. |
SERIAL_MCP_MIRROR |
off |
PTY mirror mode: off, ro (read-only), or rw (read-write). macOS and Linux only. |
SERIAL_MCP_MIRROR_LINK |
/tmp/serial-mcp |
Base path for PTY symlinks. Connections get numbered: /tmp/serial-mcp0, /tmp/serial-mcp1, etc. |
SERIAL_MCP_LOG_LEVEL |
WARNING |
Python log level (DEBUG, INFO, WARNING, ERROR). Logs go to stderr. |
SERIAL_MCP_TRACE |
enabled | JSONL tracing of every tool call. Set to 0, false, or no to disable. |
SERIAL_MCP_TRACE_PAYLOADS |
disabled | Include write data in traced args (stripped by default). |
SERIAL_MCP_TRACE_MAX_BYTES |
16384 |
Max payload chars before truncation (only applies when TRACE_PAYLOADS is on). |
SERIAL_MCP_TOOL_SEPARATOR |
. |
Character used to separate tool name segments. Set to _ for MCP clients that reject dots in tool names (e.g. Cursor). |
Tools
| Category | Tools |
|---|---|
| Serial Core | serial.list_ports, serial.open, serial.close, serial.connection_status, serial.read, serial.write, serial.readline, serial.read_until, serial.flush, serial.set_dtr, serial.set_rts, serial.pulse_dtr, serial.pulse_rts |
| Introspection | serial.connections.list |
| Protocol Specs | serial.spec.template, serial.spec.register, serial.spec.list, serial.spec.attach, serial.spec.get, serial.spec.read, serial.spec.search |
| Tracing | serial.trace.status, serial.trace.tail |
| Plugins | serial.plugin.template, serial.plugin.list, serial.plugin.reload, serial.plugin.load |
Protocol Specs
Specs are markdown files that describe a serial device's protocol — connection settings, message format, commands, and multi-step flows. They live in .serial_mcp/specs/ and teach the agent what the byte stream means.
Without a spec, the agent can still open a port and exchange data. With a spec, it knows what commands to send, what responses to expect, and what the data means.
You can create specs by telling the agent about your device — paste a datasheet, describe the protocol, or just let it explore and document what it finds. The agent generates the spec file, registers it, and references it in future sessions. You can also write specs by hand.
Plugins
Plugins add device-specific shortcut tools to the server. Instead of the agent composing raw read/write sequences, a plugin provides high-level operations like mydevice.read_temp or ota.upload_firmware.
The agent can also generate Python plugins (with your approval). It explores a device, writes a plugin based on what it learns, and future sessions get shortcut tools — no manual coding required.
To enable plugins:
# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp
# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp
Editing an already-loaded plugin only requires serial.plugin.reload — no restart needed.
Tracing
Every tool call is traced to .serial_mcp/traces/trace.jsonl and an in-memory ring buffer (last 2000 events). Tracing is on by default — set SERIAL_MCP_TRACE=0 to disable.
Event format
Two events per tool call:
{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"serial.read","args":{"connection_id":"s1"},"connection_id":"s1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"serial.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"s1"}
connection_idis extracted from args when present- Write
datais stripped from traced args by default (enable withSERIAL_MCP_TRACE_PAYLOADS=1)
Inspecting the trace
Use serial.trace.status to check config and event count, and serial.trace.tail to retrieve recent events — no need to read the file directly.
PTY Mirror
When the MCP server owns a serial port, most OSes prevent any other process from opening it. PTY mirroring creates a virtual clone port that external tools (screen, minicom, logic analyzers, custom scripts) can connect to simultaneously.
# Enable read-only mirror
claude mcp add serial \
-e SERIAL_MCP_MIRROR=ro \
-- serial_mcp
# After opening a connection, the response includes the mirror path:
# { "mirror": { "pty_path": "/dev/ttys004", "link": "/tmp/serial-mcp0", "mode": "ro" } }
# In another terminal:
screen /tmp/serial-mcp0 115200
| Mode | Behavior |
|---|---|
off |
No mirror (default). Only the MCP server can access the port. |
ro |
External tools see all serial data but cannot write to the device. |
rw |
External tools can both see data and write to the device. |
Platform: macOS and Linux only. On Windows, setting SERIAL_MCP_MIRROR to ro/rw logs a warning and is silently ignored.
Try without an agent
You can test the server interactively using the MCP Inspector — no Claude or other agent needed:
npx @modelcontextprotocol/inspector python -m serial_mcp_server
Open the URL with the auth token from the terminal output. The Inspector gives you a web UI to call any tool and see responses in real time.
Known limitations
- Single-client only. The server handles one MCP session at a time (stdio transport). Multi-client transports (HTTP/SSE) may be added later.
- Exclusive access. Without PTY mirroring, the MCP server must own the serial port exclusively.
Safety
This server connects an AI agent to real hardware. That's the point — and it means the stakes are higher than pure-software tools.
Plugins execute arbitrary code. When plugins are enabled, the agent can create and run Python code on your machine with full server privileges. Review agent-generated plugins before loading them. Use SERIAL_MCP_PLUGINS=name1,name2 to allow only specific plugins rather than all.
Writes affect real devices. A bad command sent to a serial device can trigger unintended behavior, disrupt other connected systems, or cause hardware damage (e.g., wiping flash, entering bootloader mode, triggering actuators). Consider what the agent can reach.
Use tool approval deliberately. When your MCP client prompts you to approve a tool call, consider whether you want to allow it once or always. "Always allow" is convenient but means the agent can repeat that action without further confirmation.
This software is provided as-is under the MIT License. You are responsible for what the agent does with your hardware.
License
This project is licensed under the MIT License — see LICENSE for details.
Acknowledgements
This project is built on top of the excellent pyserial library for cross-platform serial communication in Python.
serial MCP questions
How do I add serial MCP to Claude Code?
Run claude mcp add serial-mcp-server -- uvx serial-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add serial MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What hardware protocols does this server support?
It supports RS232 and UART communication.
Can I use external tools like screen or minicom while the agent is connected?
Yes, by enabling PTY mirroring, you can create a virtual clone port that external tools can connect to simultaneously.
How can I make the agent understand my specific device protocol?
You can attach protocol specs, which are markdown files describing connection settings, message formats, and commands.