# serial-mcp-server [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/es617/serial-mcp-server.git  
**GitHub Stars:** 26  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/serial-mcp-server

## Description
Let AI agents interact with serial devices — list ports, connect, send, and read.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "serial-mcp-server": {
    "command": "uvx",
    "args": ["serial-mcp-server"]
  }
}
```

## Documentation

## What serial-mcp-server does

The serial-mcp-server MCP server exposes serial-device operations to MCP-compatible AI clients. It is intended for RS232 and UART workflows on macOS, Windows, and Linux, using pyserial for the underlying connection layer. Communication with the MCP client takes place over stdio.

Agents can scan for available ports, open and close connections, inspect connection state, and exchange data. Read and write operations support text, hexadecimal, and base64 representations. Line-based operations cover reading a line or collecting data until a delimiter. Buffer flushing and DTR/RTS controls support workflows such as resetting a board or entering a boot mode.

## How it works

The server maintains connection state so an agent can perform a sequence of operations against an open port. A typical flow is to list ports, open one with the required serial settings, toggle a control line if needed, send a command, and read the response. Connection options include baud rate, parity, stop bits, and encoding.

Protocol specs provide a higher-level description of a device. Markdown files can document connection settings, message formats, commands, and multi-step procedures. After a spec is registered and attached, the agent has information about expected commands and responses rather than treating every exchange as unexplained bytes.

Plugins add device-specific tools above the raw serial layer. They can represent operations such as reading a value or uploading firmware, and the server can load or reload approved plugins. PTY mirroring can also expose a session to tools such as screen, minicom, or custom scripts.

## Setup and configuration

Install the package with `pip install serial-mcp-server`, then register the `serial_mcp` command with an MCP client. The repository also documents editable installation with `pip install -e .` or `uv pip install -e .`. The serial-mcp-server MCP server can be registered with Claude Code, configured in VS Code or Copilot through `.vscode/mcp.json`, or added to Cursor through `.cursor/mcp.json`.

No environment variable is required for the basic server. Optional settings include `SERIAL_MCP_MAX_CONNECTIONS` for the connection limit, `SERIAL_MCP_PLUGINS` for enabling all or selected plugins, and `SERIAL_MCP_LOG_LEVEL` for stderr logging. Tracing is enabled by default and can be controlled with `SERIAL_MCP_TRACE`, `SERIAL_MCP_TRACE_PAYLOADS`, and `SERIAL_MCP_TRACE_MAX_BYTES`.

Cursor users should set `SERIAL_MCP_TOOL_SEPARATOR` to `_`, because that client does not accept dots in tool names. `SERIAL_MCP_MIRROR` enables PTY mirroring with `off`, `ro`, or `rw`; mirroring is supported on macOS and Linux.

## Tools and capabilities

The documented tool groups include:

- Serial core: port listing, open and close, status, reads, writes, line reads, delimiter reads, flushing, and DTR/RTS control.
- Introspection: listing active connections.
- Protocol specs: creating templates, registering, listing, attaching, retrieving, reading, and searching specs.
- Tracing: checking trace status and viewing recent trace entries.
- Plugins: generating templates, listing, reloading, and loading plugins.

The serial-mcp-server MCP server supports a progression from raw byte exchange to documented protocols and reusable device operations. Agents can use these layers for conversational debugging, repeatable test sequences, hardware smoke tests, and device exploration.

## Limitations and notes

Plugin use is disabled unless enabled through configuration, either for all plugins or for named plugins. PTY mirroring is not available on Windows according to the documented platform support. The server communicates over stdio, so the MCP client must support that transport and the host must have access to the target serial device.

Trace payloads are omitted by default; enabling payload tracing includes write data and applies the configured maximum length. The default maximum simultaneous connection count is 10, and the default tool-name separator is a period unless changed for client compatibility.

_Full upstream README: https://allmcps.com/mcp/serial-mcp-server/readme_