Serial Console MCP: AI for telecom equipment and any serial device

serial-console-mcp

通过设备已有的控制台端口，使用 AI 配置电信设备。

 MIT licensed  ·  Python 3.10+  ·  状态：0.3.2，已在 Juniper EX2200 控制台上完成真实验证

serial-console-mcp 可将 Claude 等 AI 助手连接到网络和广播设备的串行控制台，以及任何其他带有串行端口的设备：

• 路由器和交换机。 Juniper（Junos）和 Cisco（IOS、IOS-XE）的控制台和维护端口：登录、读取状态、借助安全保护措施更改配置（Junos 上的 commit confirmed，IOS 上的 reload in），并恢复控制台原状。
• 无线电收发器。 通过 CI-V 连接 Icom 和 Xiegu；通过文本 CAT 协议连接 Kenwood、Yaesu 和 Elecraft：识别设备、读取和设置频率与模式。
• 天线旋转器。 Yaesu GS-232 及众多支持该协议的控制器：读取方位、转动、停止。
• 任何其他带有串行端口的设备。 本服务并不限于电信设备：它可处理原始字节、清理 ANSI 输出，或保留完整的 VT100/xterm 屏幕，因此也适用于 IoT 网关、报警和门禁控制面板、UPS 和 PDU 菜单、实验室仪器、工业控制器、Linux 和 BIOS 控制台以及微控制器。

你只需用日常语言说明需求。助手通过本服务操作控制台，Claude Desktop 会逐步请求你批准，而内置的操作技能则会教它 Junos 和 IOS 的基础知识：提示符代表什么模式、如何进入和退出，以及哪些 show 命令能解答日常问题。

Juniper 支持已在真实的 EX2200 控制台上完成验证。Cisco、CI-V、CAT 和旋转器支持基于厂商协议参考资料实现，尚未在此处连接实际硬件进行测试。其他设备类型使用通用工具，而非特定设备的辅助工具。

**你不需要懂任何编程。**安装后，你可以像平常一样与 Claude 对话：

**你：**能看到哪些串行端口？ **Claude：**我找到了两个。其中一个看起来是 COM4 上的 Silicon Labs CP210x——那可能就是你的设备。

**你：**以 9600 波特率连接 COM4。 **Claude：**已连接。

**你：**登录并给我看看版本。

工作原理（重要部分）

串行控制台并非简单的问答通道。它会回显你输入的内容，自行输出未经请求的消息（日志、接口状态变化），还可能一次输出多页内容。因此，端口一旦打开，后台读取器就会持续读取数据并存入缓冲区。这意味着 Claude 可以：

• 发送命令（只负责写入，不会猜测回复何时结束），然后
• 读取直至出现提示符（# 、> 、login:……），从而获取完整回复——即使回复很长也不会被截断，或者
• 读取当前所有待处理内容，用于接收流式输出或未经请求的输出。

这与 minicom 和 expect 使用的模式相同，因此可以妥善处理交互式 CLI。

工具

工具	功能
list_serial_ports	列出串口及其描述和 USB 硬件 ID；标记当前已打开的端口
list_presets	各设备系列的常用设置：Cisco/Juniper/Linux 控制台、全屏控制台（BIOS、BMC、菜单）、Kenwood/Elecraft/Yaesu CAT、Icom 和 Xiegu CI-V、转台、Arduino、NMEA GPS
connect / reconnect_last / disconnect	按名称打开端口。默认设置为 9600 8N1，无流控；波特率、数据位、校验位、停止位、RTS/CTS、XON/XOFF、行尾和提示符均可设置，也可从预设加载。可同时打开多个端口
send_keys / screen	按名称发送 Ctrl-C、Esc、Tab、方向键、功能键；查看全屏控制台（BIOS、BMC、菜单交换机、vi）的 VT100/xterm 屏幕
send_text / send_hex	写入 ASCII 行（CR / LF / CRLF / 无）或原始十六进制字节。仅写入
read_until_prompt	返回缓冲输出，直到遇到字面提示符或正则提示符，并保留其余内容；auto_reply 会翻阅 --More-- 分页
read_available	以文本和十六进制形式返回已接收的所有内容
query_text	清除缓冲区、发送内容，然后读取，直到遇到提示符或该行进入空闲状态
expect	在一次调用中执行脚本化的发送和等待步骤列表：登录、命令序列
set_lines / pulse_line / send_break	控制 DTR 和 RTS（PTT、Arduino 重置），发送 BREAK
capture_start / capture_stop / get_transcript	将会话记录到文件（原始记录或带时间戳的 TX/RX）；重新读取滚动转录记录
port_in_use_by / detect_baud	查看哪个程序占用端口；查看哪个波特率能生成可读文本
cat_build / cat_parse	Kenwood、Elecraft 和 Yaesu ; 命令：生成频率设置，解码 ID、FA、MD、IF 和错误回复
civ_build / civ_parse / civ_freq	Icom CI-V 帧：生成、解码（回显与回复、BCD 频率、模式、PTT）、转换
rotator_build / rotator_parse	GS-232 转台命令（读取、移动、停止、速度）和位置回复
clear_buffer / status	日常维护；status 会显示每个已打开端口及其控制线状态

按名称（“rig”、“rotator”）打开端口；工具默认使用最近使用的端口。每个连接都有一种终端模式：dumb（原始字节，默认模式）、ansi（去除颜色和转义序列，应用 CR/退格覆盖；即使设备通过空格和退格重绘提示符，也会按显示内容匹配；控制台预设使用此模式），或 xterm/vt100（可通过 screen 查看真实屏幕；需要 pip install 'serial-console-mcp[screen]'，桌面扩展中已包含）。每个端口的接收缓冲区上限为 4 MB；如果设备持续输出数小时而未读取，最早的字节会被丢弃，status 会显示丢弃的字节数。

操作技能

skills/ 中的三个技能文件会教 Agent 如何规范操作，方式与 fldigi-mcp 技能相同；将它们复制到 ~/.claude/skills/ 或项目的 .claude/skills/：

技能	教授内容
serial-console	控制台模型、六条规则、终端模式、按键、预设
junos-operating	根据提示符识别 Junos 模式（% shell、> operational、# configure），从 BSD shell 退出并返回，configure exclusive、show | compare、commit confirmed、rollback、cli -c 和 start shell；在 EX2200 上验证过的运行状况和接口 show 命令（show chassis routing-engine、show interfaces terse/brief）
ios-operating	IOS 模式（>、#、(config)#）、enable/configure terminal/end、作为安全保障的 reload in 10、write memory、日常 show 命令（show ip interface brief、show processes cpu sorted）

环境变量

变量	效果
SERIAL_CONSOLE_READ_ONLY=1	除只读风格的命令（show、ID;、CI-V 读取）外，拒绝写入，并拒绝更改控制线
SERIAL_CONSOLE_ALLOW=<regex>	覆盖只读允许列表
SERIAL_CONSOLE_IDLE_MINUTES=15	端口空闲这么久后自动关闭（默认：永不）

在 claude_desktop_config.json 中该服务对应的条目下，通过 "env" 设置这些变量。

安装

1. 从 Releases 页面 下载 serial-console-mcp.mcpb。 Mac、Windows 和 Linux 均可使用同一个文件。
2. 在 Claude Desktop 中，前往 Settings → Extensions → Advanced settings → Install Extension…，然后选择该文件。简短的设置表单提供只读模式和空闲超时选项；除非启用，否则两者均处于关闭状态。
3. 在新聊天中输入：“你能看到哪些串口？” 如果 Claude 列出了你的端口，就完成了。

无需终端、无需 Python，也无需手动配置。

从 0.3.x 的 .pkg 或 .exe 安装程序升级？ 请先移除旧版本，否则 Claude Desktop 会启动两个服务。在 Mac 上：

"/Library/Application Support/SerialConsoleMCP/serial-console-mcp" configure --remove
sudo rm -rf "/Library/Application Support/SerialConsoleMCP"

在 Windows 上，在“设置 → 应用”中卸载 Serial Console MCP。然后退出并重新打开 Claude Desktop。

从 PyPI 安装

如果你已经安装了 Python 3.10+ 和 uv 或 pipx， 可以跳过扩展：

uvx serial-console-mcp --version                                   # fetches and runs it
uvx serial-console-mcp configure --command uvx --arg serial-console-mcp

或

pipx install serial-console-mcp
serial-console-mcp configure --command "$(which serial-console-mcp)"

configure 会在 claude_desktop_config.json 中写入一个 serial-console 条目（与已有内容合并，并先备份旧文件）。 退出并重新打开 Claude Desktop。运行 serial-console-mcp configure --remove 可撤销此操作。其他 MCP 客户端也可以通过 stdio 启动同一命令。

从源代码安装（开发者）

git clone https://github.com/sbrunner-atx/serial-console-mcp.git
cd serial-console-mcp
uv sync                       # or: python3 -m venv .venv && . .venv/bin/activate && pip install -e . pytest
uv run pytest                 # fake serial port, no hardware needed
uv run serial-console-mcp configure --command "$PWD/.venv/bin/serial-console-mcp"

此软件包位于 src/serial_console_mcp/：server.py 是 MCP 服务，configure.py 是 Claude Desktop 注册工具。manifest.json 描述桌面扩展；npx @anthropic-ai/mcpb pack 可构建该扩展。BUILD.md 介绍已弃用的 .pkg 和 .exe 安装程序。

使用方法

可以使用日常用语提出请求。以下是一些示例：

• “列出我的串口。”
• “以 9600 波特率连接到 /dev/cu.usbserial-10 上的控制台。”
• “以 38400 波特率、8 个数据位、无校验、1 个停止位和 XON/XOFF 流控连接到 /dev/cu.BLTH。”
• “使用 kenwood-cat 预设连接 Kenwood，并将其命名为 rig；在另一个端口上连接转子。”
• “以 admin 身份登录并运行 show version”（一次 expect 调用：回车、登录、密码、命令）。
• “这台设备的波特率是多少？”（detect_baud）。
• “让电台发射两秒”（pulse_line("RTS", 2000)，确认后执行）。
• “询问 IC-7300 的频率”（civ_build、send_hex、read_available、civ_parse）。
• “TS-590 调到了什么频率？”（query_text("FA;")、cat_parse）。
• “将转子转到 45 度并确认”（rotator_build、query_text、rotator_parse）。
• “将这次控制台会话记录到文件中。”
• “按 Ctrl-C，ping 还在运行。”（send_keys）
• “以 115200 波特率打开 BIOS 控制台并显示屏幕；向下移动两行，然后按 Enter。”（screen-console 预设、screen、send_keys）
• “重新连接到上次使用的同一端口。”（它会记住）
• “发送回车，然后读取直到出现登录提示。”
• “以 admin 身份登录并运行 show interfaces terse，然后把完整输出给我看。”
• “只读取设备当前正在输出的内容。”
• “完成后断开连接。”

对于路由器／交换机控制台，请告诉 Claude 它应等待的提示符（通常是启用模式下的 # 或用户模式下的 > ），它会一直读取，直到看到该提示符。对于 Icom 电台（CI-V），告诉 Claude——它可以发送这些电台所需的十六进制命令。

如果出现问题

“未找到串口。”

• 设备是否已开机？
• USB 线缆是否是真正的数据线，而不是只能充电的线？（这是一个很常见的疏忽。）
• 在 Windows 上，打开设备管理器并查看端口（COM 和 LPT）。如果那里什么都没有，Windows 就需要安装线缆的驱动程序（通常是 FTDI、CP210x 或 CH340）。

“无法打开端口”/“访问被拒绝。”

• 串口一次只能由一个程序使用。关闭其他可能占用端口的程序：终端（PuTTY/minicom/screen）、WSJT-X、竞赛日志软件或设备自带的软件。

Claude 表示无法访问串口。

• 确保安装后已完全退出并重新打开 Claude Desktop。
• 新建一个聊天，再问一次“你能看到哪些串口？”

已连接，但命令没有收到回复。

• 几乎总是因为波特率不正确，或者设备所需的换行符不正确。大多数类 Unix 控制台需要普通换行符（LF）；大多数电台需要回车符（CR）。让 Claude 先发送一个回车符，以显示新的提示符。

关于安全的一点说明

这些工具会将你（通过 Claude）要求发送的内容原样发送到连接线缆的设备。Claude Desktop 会要求你批准每次工具调用，因此你可以在命令运行前查看它。请仔细阅读。路由器或电台上的控制台会话可能会重新配置、重启或发射，而此服务不会尝试判断哪些命令有危险。如果发现任何不妥，请拒绝操作；对于任何你不希望助手输入的内容，请准备好一个真正的终端。

许可证

MIT。请参阅 LICENSE。

73！