The Serial Console

A · The tools at a glance

One server provides thirty tools and can hold open as many ports as the shack has cables. You say what you want in plain language, and the agent picks the tool. None of this is tied to telecom. If a device has a serial port and speaks raw bytes, ANSI or VT100, the same tools drive it.

B · Installing

The server runs on your own computer, started by Claude Desktop, so it can see /dev/cu.*, COM4 or /dev/ttyUSB0.

As a desktop extension (recommended)

1. Download the bundle. Get serial-console-mcp.mcpb from Downloads. The same file works on Mac, Windows and Linux.
2. Install it. In Claude Desktop, go to Settings → Extensions → Advanced settings → Install Extension and choose the file. You do not need a terminal or a Python install.
3. Settings, if you want them. The form offers read-only mode and a timeout that closes a forgotten port. Both are off unless you turn them on.

From PyPI (uv or pipx)

uvx serial-console-mcp configure --command uvx --arg serial-console-mcp
# or
pipx install serial-console-mcp
serial-console-mcp configure --command "$(which serial-console-mcp)"

This needs Python 3.10 or newer. configure writes the Claude Desktop entry. It keeps the servers already listed there and backs up the old file. serial-console-mcp configure --remove undoes it. Any MCP client can launch the same command over stdio. Developers: git clone, uv sync, uv run pytest.

Check that it works (thirty seconds)

1. Ask for the ports. "What serial ports do you see?" A list with USB descriptions means the server is running and the OS sees your adapter. "No serial ports found" with the device plugged in almost always means a charge-only USB cable or a missing driver (FTDI, CP210x, CH340).
2. Open and close a port. "Connect to the first one, show me the status, then disconnect." Status should say the reader is running with zero bytes buffered.

C · Your first session

You do not need to know a terminal program. If you can plug in a cable and describe your gear, you can operate it.

What you are installing

Claude is an assistant made by Anthropic. It runs in the Claude Desktop app. Think of serial-console-mcp as a rig-interface cable with a patient operator on the other end. Claude types what you ask into the port, watches what comes back, and tells you. Nothing about your device changes. It sees an ordinary terminal. The cable does not care what is on the other end. A switch, a radio, an alarm panel, an IoT gateway and a lab instrument all look the same to it.

Operating is a conversation

D · How the system works

A serial console does not work in neat question-and-answer pairs. It echoes what you type, prints things on its own, and can dump pages of output. So the server never guesses when a reply is done. It keeps reading, and you tell it what the end of a reply looks like.

• The reader owns the port. One thread empties the OS buffer continuously. Echo, unsolicited syslog and a three-page show run all arrive intact, with no ad-hoc polling racing to catch them. minicom and expect work the same way.
• Reads end at the prompt, not on a timer. read_until_prompt returns as soon as the prompt shows up. It hands back everything up to and including the prompt. A fixed delay would cut off long output or waste seconds on short output. Waiting for the prompt avoids both.
• Leftover bytes are kept. Bytes after the matched prompt go back to the front of the buffer, so an unsolicited line that arrived mid-read is the first thing the next read sees.
• Timeouts return what they have. If the prompt never shows, you still get the partial output with a note to try again or change the prompt.
• A dead port is reported. If you unplug the adapter, the reader stops. Every tool then says so and asks you to reconnect, instead of timing out with no message.
• Memory use is limited. The buffer holds four megabytes. If a device streams for hours and nobody reads it, the oldest bytes are dropped, and status reports how many.

01 · Connection settings

You can say everything in a terminal program's Quick Connect dialog in one sentence. The default is 9600-8-N-1 with no flow control. Most consoles and much radio gear expect that, so name only what differs.

Shorthand works too. "38400 8N1", "9600 7E1" and "the usual Cisco console settings" all resolve to the right parameters. The agent repeats the settings back in the connect reply, so a misheard baud rate is visible before the first command goes out.

Presets

connect(preset="kenwood-cat") loads a family's usual settings. That includes two settings the dialog never asks for: the line ending the device expects, and the prompt that ends its replies. Anything you say explicitly overrides the preset. The presets are cisco-console, juniper-craft, linux-console, kenwood-cat, elecraft-cat, yaesu-cat, icom-civ, xiegu-civ, yaesu-rotator, arduino, nmea-gps, screen-console. Presets also choose the terminal mode (chapter 05). The console presets strip colors and escape sequences, and the radio presets pass raw bytes. Ask "list the presets" to see each one's values and caveats. The presets hold factory defaults. If the device's menu says something different, go with the menu.

If you do not know the rate at all, ask "What baud is this thing?". That runs detect_baud. It tries the common rates, sends a return (or a command you name, such as ID; for a Kenwood), and ranks the rates by how readable the reply is.

Flow control settings

• Leave both off unless the manual says otherwise. Almost all consoles, CAT ports and microcontrollers run without flow control.
• RTS/CTS needs the wires. Many console cables and three-wire adapters do not carry RTS and CTS. If you turn it on with such a cable, every write waits for a CTS that never comes. The server gives up after two seconds and tells you that is what happened.
• XON/XOFF is for text only. It treats the bytes 0x11 and 0x13 as flow-control characters and swallows them. Never enable it for Icom CI-V or any other binary protocol. A frequency that contains those bytes would be corrupted with no warning.

Remembered across sessions

Every successful connect saves the connection to a small file in your user profile. The file keeps the connection's name, all its settings, the preset and the prompt. "Reconnect to the rig" or "reconnect to the same port as last time" reads it back. status shows what is remembered when nothing is open.

02 · The console standard

The tools are built around six rules. Each rule avoids a trap that a naive send-and-wait approach falls into.

1. Sending never reads. send_text and send_hex put bytes on the wire and return. Reading the reply is a separate step. That is how the agent can log in (send, wait for Password:, send, wait for the shell) without guessing at delays.
2. Name the prompt with its trailing space. The match runs over everything received, including the echo of your own command. "# " is safe. A bare "#" matches the first # in a banner or in show run | include #. A regex such as [\w.-]+[#>] ?$ handles hostnames that change after configure. Set the prompt once on connect (or let the preset set it), and every read uses it. If no prompt is set anywhere, the read ends when the received text ends in #, >, $ or %.
3. Clear before a command whose reply must be clean. Syslog, interface flaps and a previous timed-out read leave bytes in the buffer. send_text(…, clear_buffer_first=true) or query_text discard them so the next read starts at your echo.
4. Use text prompts for CLIs and idle reads for everything else. For routers, switches and shells, use read_until_prompt. Binary protocols and one-line CAT answers have no prompt. For those, use read_available, or query_text with an empty prompt, which returns once the line has been quiet for a moment.
5. A wrong baud rate looks like garbage. A wrong line ending looks like silence. A stream of replacement and box characters means the baud rate is wrong. An echo with no reply means the device is waiting for the other line ending. Send a bare return first to get a fresh prompt. If that also produces nothing, check the cable.
6. Disconnect before handing the port to anything else. The OS gives a port to one process. A forgotten open port is the most common reason WSJT-X or a terminal program cannot find a device that is clearly plugged in.

03 · The device playbook

Four device families have their own playbook. The last row covers anything else on a serial port. The settings below are the common factory defaults. When the device's manual or menu says otherwise, go with the device.

04 · The shack: several ports, control lines, scripts, capture

This chapter covers what release 0.2 added on top of the console model. You can name ports, drive the lines that key and reset, script a login in one call, and keep a record of a session.

Several ports at once

Every connection has a name, as in "connect the Kenwood as rig, then the rotator on the other port as rotator". Tools act on the most recently used connection unless you say otherwise, as in "ask the rig for its frequency, then turn the rotator to 180". status lists all of them and marks the current one. "Disconnect everything" closes them all. Connecting to a port that is already open replaces that connection. Reusing a name for a different port is refused, so rig can never silently become the amplifier.

Control lines

Scripting with expect

A login takes four round trips: return, username, password, first command. expect runs them in one call. Each step is a send and the prompt to wait for, and the call returns every step's output. A step can also only wait, or only send. auto_reply answers pagers along the way. With {"--More--": " "}, a paged show run comes back as one result. If a step's prompt never shows up, the sequence stops there, says so, and returns whatever arrived.

expect(steps=[
  {"send": "",             "expect": "login: "},
  {"send": "admin",        "expect": "Password:"},
  {"send": "<password>",   "expect": "> "},
  {"send": "show version", "expect": "> ", "clear_first": true}
])

Capture and transcript

"Record this session" starts a capture. The raw format writes received bytes unchanged as they arrive, like a terminal log. The annotated format writes timestamped lines marked TX or RX, which is what you want when debugging a protocol. capture_stop reports the file. Separately from any capture, the last 256 KB received on every connection is kept as a transcript. So "show me what the router printed earlier" works even after a read has used up those bytes. MCP clients that browse resources see the same transcript as serial://transcript/<name>.

Read-only mode and idle auto-close

Two environment variables in the server's config entry control these. SERIAL_CONSOLE_READ_ONLY=1 makes the server refuse anything but read-style commands (show, display, two-letter CAT reads such as ID;, CI-V read frames) and refuse control-line changes. This is how a cautious admin can try the tool on a production console. SERIAL_CONSOLE_IDLE_MINUTES=15 closes a port that nobody has used for that long, so a forgotten connection stops blocking WSJT-X. Both are off by default.

05 · Terminals: clean text, keys, and a real screen

A terminal program offers a menu of emulations: VT100, VT220, Xterm, ANSI, Linux, Wyse, TN3270. An agent needs three of them, and this chapter covers those three. The rest of the menu is either the same family under another name, or a 1980s terminal nobody has plugged in for twenty years.

Three terminal modes

Choose the mode with connect(terminal=…), or let the preset choose it. The capture file and the screen model always keep the raw bytes. Only what the read tools return is cleaned. The screen model needs the [screen] extra (pip install 'serial-console-mcp[screen]'). The desktop extension includes it. Without it, xterm falls back to ansi and tells you so.

Prompts on a redrawn line

If you ask Junos for help with show system ?, or clear the line with Ctrl-U, it does not print a fresh prompt. Instead it sends a carriage return, retypes the line, pads it with spaces and backs up over them. So the bytes end in show system   \b\b\b rather than in > . In ansi, vt100 and xterm mode, read_until_prompt and expect also try the pattern on the last line as the screen shows it, up to the cursor. After Ctrl-U, the preset's [#>%] ?$ finds root@sw> . After ?, the pattern > show system $ finds the retyped words. A line that has ended, or that a carriage return has just rewound, is never taken for a prompt. dumb mode matches the bytes as they are, backspaces and all. Tab completion does not cause this problem. On Junos 15.1 it only adds the rest of the word in place, so it needs no special handling.

Keys by name

send_text types a line. send_keys presses keys, as in "hit Ctrl-C, that ping is still running", "press Tab to complete it", or "arrow down twice and Enter". The key names are the obvious ones: ctrl-c through ctrl-z, esc, tab, enter, backspace, delete, up, down, left, right, home, end, pgup, pgdn, f1 to f12, a single character, or text:… for a literal run. They are encoded the way an xterm sends them, which is what every current device expects. send_keys does not read anything. Look at the reply with read_until_prompt, read_available or screen.

Read-only mode and keys

In read-only mode, named keys are allowed, because interrupting and navigating never change configuration by themselves. Single characters and text: runs are refused, since those count as typing.

06 · Junos and IOS, the basics

The server deals with bytes and prompts. Two skills teach the agent what the prompts mean on the two console families it will meet most. They cover how to tell which mode it is in, how to move from one mode to another, how to change something without cutting off its own connection, and which show commands answer the everyday questions. Both live in skills/ and load the way the fldigi skills do.

junos-operating

The skill enforces these rules. Read the prompt before every action. Use configure exclusive, not bare configure. Show the user show | compare before any commit. Use commit confirmed for anything that can cut the path you are on, then a plain commit once you have verified the device is still reachable. To undo, use rollback 1, then commit.

Before anything long, send set cli screen-length 0 once, or add | no-more. At a ---(more pager, every key is a pager command (q quits, s saves the output to a file). So press q before typing the next command. If you are not sure a command exists, type ? after the words so far, clear the line with Ctrl-U, and read the prompt again. The ansi terminal matches the prompt on the redrawn line, so no extra return is needed.

ios-operating

IOS has no commit, so the procedure is different. Send reload in 10 before any change that could cut the path. Then verify, send reload cancel, then write memory. Undo a line by putting no in front of it. IOS-XE with archive has configure replace. IOS has no shell underneath to get out of. The only prompts that are not the CLI are the boot monitor and the setup dialog.

Send terminal length 0 once per session. IOS pipes are include, exclude, begin, section and count. The pipes last and no-more are Junos only.

E · Worked sessions

There are five sessions, one per family. Each shows what you say, what the agent sends, and what comes back. The device replies are representative, not recordings.

1 · Juniper craft port: log in and read a version

9600 8N1 · LF · read_until_prompt

Why it worked. The preset supplied CR and the prompt regex. Each step named the next prompt to wait for. clear_first made the last reply begin at the echo. It took one approval and one round trip.

2 · Kenwood-style CAT: identify the rig and read the VFO

38400 8N1 · no line ending · query_text

Why it worked. The preset supplied both things the dialog never asks for. It set no line ending (Kenwood parsers reject a CR) and ; as the prompt, so each reply returned as soon as it was complete. cat_parse turned the codes into a model and a frequency.

3 · Icom CI-V: read the operating frequency in hex

19200 8N1 · send_hex → read_available

Why it worked. CI-V is a binary protocol, so the hex view is the answer, and civ_parse does the BCD arithmetic. The rig's USB interface echoes, and the parser labels the echo so it is not mistaken for a reply. XON/XOFF was off, so no byte of the binary frame could be mistaken for flow control.

4 · Arduino sensor: watch a stream, then stop it

115200 8N1 · LF · read_available

Why it worked. A device that talks on its own has no prompt and needs no query. read_available with a longer timeout captures a window of output (capture_start would keep all of it in a file). disconnect frees the port for the Arduino IDE.

5 · Rotator: read the heading, turn to Europe, confirm

9600 8N1 · CR · yaesu-rotator preset

Why it worked. Two ports were open at once, each with its own preset. The rotator's CR line ending and "\r" reply terminator came from its preset. A move is confirmed by reading the position back, never assumed.

F · When it does not answer

Most silent ports come down to one of the causes below. The server's own messages point to many of them.

G · Tool reference

These are the parameters as the agent sees them, with defaults in brackets. Every tool that acts on a port takes connection [current].

Other details

• Non-ASCII text in send_text is sent as ?. Use send_hex for raw bytes.
• Display decoding is UTF-8 with replacement characters. Prompt matching works on the exact bytes, so binary noise before a prompt does not shift the match.
• The write timeout is two seconds. The reader polls every tenth of a second. A read with no prompt returns after 150 ms of quiet. The receive buffer holds 4 MB per port, and the transcript holds 256 KB.
• Remembered connections live in last_connection.json under ~/Library/Application Support/serial-console-mcp/ (Mac), %APPDATA%\serial-console-mcp\ (Windows), ~/.config/serial-console-mcp/ (Linux). Captures that are named automatically go in a captures folder beside it.
• Terminal modes change only what the read tools return. The capture file and the screen model always get the raw bytes. If an escape sequence is split across two reads, the stripper holds it until it is complete.
• The operating skill in skills/serial-console/SKILL.md carries this guide's rules for the agent.

H · About and provenance

Release 0.3.2 was run against real hardware on 15 September 2026. This guide claims only what has been verified.

serial-console-mcp began as a generic console tool for network craft ports and radio gear. For this release it was rewritten around the background-reader model described in chapter D. The 0.3.2 code is verified three ways. An 83-case test suite drives a simulated serial port. Continuous integration runs on Linux, macOS and Windows. And a live session ran on 15 September 2026. In that session the PyPI package, launched by uvx the same way Claude Desktop launches it, drove a Juniper EX2200-C (Junos 15.1R6.7) over a Prolific USB-serial adapter at 9600 8N1 with the juniper-craft preset. One expect call entered the CLI from the shell, turned off paging, and ran show version, show chassis hardware and show system uptime. Every prompt matched on the regex, and the call returned to the shell. An annotated capture recorded the session. The worked sessions in chapter E are still representative walk-throughs. The Juniper one now matches what the real switch printed.

Corrections and additions are welcome. Open an issue on the repository.