# serial-mcp-server

Hands an AI agent a live serial connection: open a port, send a command, read the reply, toggle DTR.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 26
- Author: es617
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/es617/serial-mcp-server
- Updated: 2026-03-07
- HTML: https://affpapa.org/en/nevibecode/mcp/serial-mcp-server

## What it does

The server keeps connection state and talks to the client over stdio. On top of pyserial it exposes tools for listing ports, opening and closing with baud rate, parity, stop bits and encoding, then reading and writing as text, hex or base64. Text protocols get readline and read-until-delimiter calls. DTR and RTS can be set or pulsed, which is how you reset a board or drop it into a bootloader.

Beyond raw bytes, the agent can lean on protocol specs and device plugins. A spec spells out the command set and output format; a plugin turns common operations into one call. Plugins stay off until `SERIAL_MCP_PLUGINS` is set to `all` or a comma-separated list of names. There is also PTY mirroring, so `screen`, `minicom` or your own script can watch the session the agent is using. That part is macOS and Linux only.

You need Python 3.11 or newer. Up to 10 connections can be open at once; change that with `SERIAL_MCP_MAX_CONNECTIONS`. Cursor rejects dots in tool names, so set `SERIAL_MCP_TOOL_SEPARATOR` to `_` in its config — skip it and the tools will not register there.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `SERIAL_MCP_MAX_CONNECTIONS`, `SERIAL_MCP_PLUGINS`, `SERIAL_MCP_MIRROR`, `SERIAL_MCP_MIRROR_LINK`, `SERIAL_MCP_TOOL_SEPARATOR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env SERIAL_MCP_MAX_CONNECTIONS=<SERIAL_MCP_MAX_CONNECTIONS> --env SERIAL_MCP_PLUGINS=<SERIAL_MCP_PLUGINS> --env SERIAL_MCP_MIRROR=<SERIAL_MCP_MIRROR> --env SERIAL_MCP_MIRROR_LINK=<SERIAL_MCP_MIRROR_LINK> --env SERIAL_MCP_TOOL_SEPARATOR=<SERIAL_MCP_TOOL_SEPARATOR> --transport stdio serial-mcp-server -- uvx serial-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from serial-mcp-server <command>

### Codex

**Platform CLI**
```bash
codex mcp add serial-mcp-server --env SERIAL_MCP_MAX_CONNECTIONS=<SERIAL_MCP_MAX_CONNECTIONS> --env SERIAL_MCP_PLUGINS=<SERIAL_MCP_PLUGINS> --env SERIAL_MCP_MIRROR=<SERIAL_MCP_MIRROR> --env SERIAL_MCP_MIRROR_LINK=<SERIAL_MCP_MIRROR_LINK> --env SERIAL_MCP_TOOL_SEPARATOR=<SERIAL_MCP_TOOL_SEPARATOR> -- uvx serial-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from serial-mcp-server <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "serial-mcp-server": {
            "command": "uvx",
            "args": [
                "serial-mcp-server"
            ],
            "env": {
                "SERIAL_MCP_MAX_CONNECTIONS": "<SERIAL_MCP_MAX_CONNECTIONS>",
                "SERIAL_MCP_PLUGINS": "<SERIAL_MCP_PLUGINS>",
                "SERIAL_MCP_MIRROR": "<SERIAL_MCP_MIRROR>",
                "SERIAL_MCP_MIRROR_LINK": "<SERIAL_MCP_MIRROR_LINK>",
                "SERIAL_MCP_TOOL_SEPARATOR": "<SERIAL_MCP_TOOL_SEPARATOR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from serial-mcp-server <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "serial-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "serial-mcp-server"
            ],
            "env": {
                "SERIAL_MCP_MAX_CONNECTIONS": "<SERIAL_MCP_MAX_CONNECTIONS>",
                "SERIAL_MCP_PLUGINS": "<SERIAL_MCP_PLUGINS>",
                "SERIAL_MCP_MIRROR": "<SERIAL_MCP_MIRROR>",
                "SERIAL_MCP_MIRROR_LINK": "<SERIAL_MCP_MIRROR_LINK>",
                "SERIAL_MCP_TOOL_SEPARATOR": "<SERIAL_MCP_TOOL_SEPARATOR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from serial-mcp-server <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SERIAL_MCP_MAX_CONNECTIONS=<SERIAL_MCP_MAX_CONNECTIONS> -e SERIAL_MCP_PLUGINS=<SERIAL_MCP_PLUGINS> -e SERIAL_MCP_MIRROR=<SERIAL_MCP_MIRROR> -e SERIAL_MCP_MIRROR_LINK=<SERIAL_MCP_MIRROR_LINK> -e SERIAL_MCP_TOOL_SEPARATOR=<SERIAL_MCP_TOOL_SEPARATOR> serial-mcp-server uvx serial-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from serial-mcp-server <command>

## When to use it
- locate a connected board and find its port
- read a boot banner right after reset
- replay a command sequence and check the output
- work out an unfamiliar protocol from device replies
- script reset and bootloader entry instead of doing it by hand

## Example prompts
- List the serial ports and connect to `/dev/ttyUSB0` at 115200 baud.
- Send `AT` to the port and return everything up to the newline.
- Pulse DTR, wait for the prompt, then show me the startup output.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md