Ssh Mcp Server

SSH MCP Server

[English](README.en.md)

一个面向 AI 客户端的 SSH 与串口 MCP Server。它把连接管理、终端字节流和 TUI 屏幕投影分层，使模型通过少量稳定工具完成远程命令、交互式终端和串口控制台操作。

能力

• SSH 密码和私钥认证，支持本地保存的主机配置与连接别名。
• 非交互命令执行、SFTP 传输和目录操作。
• 统一的 SSH/串口终端：写入与读取原子化，输出有偏移量、大小上限和明确的完成状态。
• SSH TUI 屏幕投影；串口保留原始字节流，适合设备 CLI、REPL 和日志控制台。
• MCP 协议只使用 stdout；所有日志写入 stderr，避免破坏握手。

快速开始

要求 Go 1.24.4 或更高版本。

git clone https://github.com/Cigarliu/ssh-mcp-server.git
cd ssh-mcp-server
go build -o bin/sshmcp ./cmd/server
cp config.example.yaml .sshmcp.yaml

在 MCP 客户端中配置标准输入输出服务：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "/absolute/path/ssh-mcp-server/bin/sshmcp",
      "args": ["-config", "/absolute/path/ssh-mcp-server/.sshmcp.yaml"]
    }
  }
}

服务也会依次查找 -config、当前目录的 .mcp.yaml / .sshmcp.yaml 和 ~/.sshmcp/config.yaml。找不到配置时会生成默认配置。

工具面

默认使用 files profile，向模型暴露 10 个工具。

| Profile | 工具数 | 用途 | | --- | ---: | --- | | core | 8 | SSH、串口与终端的日常操作 | | files | 10 | core 加聚合的 SFTP 上传、下载和目录操作 | | advanced | 27 | 兼容旧的细粒度 SSH/SFTP/诊断工具 |

默认 files 工具：

| 工具 | 说明 | | --- | --- | | connection_list | 列出活跃连接、已保存 SSH 主机和本机可见串口 | | connection_open | 创建 SSH 或串口连接；SSH 在已保存主机和直连参数之间二选一 | | connection_close | 关闭连接及附属终端 | | ssh_exec | 执行非交互 SSH 命令 | | sftp_transfer | 上传或下载单个文件 | | sftp_manage | 列出目录、创建目录或删除路径 | | terminal_open | 在已打开连接上创建通用终端 | | terminal_interact | 原子写入并按 until 字面量或静默窗口等待输出 | | terminal_view | 获取 SSH TUI 屏幕投影，不用于普通命令输出 | | terminal_close | 关闭终端；串口终端同时释放设备 |

在 files profile 中，使用 sftp_transfer 处理上传/下载，使用 sftp_manage 处理列表、创建目录和删除。

推荐调用路径

普通 SSH 命令使用 connection_open -> ssh_exec -> connection_close。

需要保持上下文、使用 REPL 或运行交互程序时：

connection_open -> terminal_open -> terminal_interact -> terminal_close -> connection_close

terminal_interact 返回结构化状态，而不是依赖任意 sleep：

• matched: 找到指定的 until 字面量文本。
• stable: 收到输出后达到静默窗口。
• limit_reached: 输出达到 max_bytes，使用 next_offset 继续读取。
• timeout 或 closed: 根据 stop_reason 决定下一步，不要盲目重试。

通常使用默认的 wait: "quiet"。只有已知完整的提示符或分隔文本时才使用 wait: "until" 和 until；它不是正则表达式。wait: "none" 仅用于暂不需要响应的写入。对于 TUI，创建 profile: "tui" 的 SSH 终端，并用 terminal_view 读取屏幕。对于串口，使用 profile: "shell" 和 terminal_interact 读取原始数据；串口没有屏幕投影。

配置

最小配置示例：

tools:
  profile: files

logging:
  level: info
  format: console
  output: stderr

hosts:
  lab:
    host: "192.168.1.100"
    port: 22
    username: "operator"
    private_key_path: "~/.ssh/id_ed25519"
    description: "Lab host"

主机名称会通过 connection_list 返回给模型，但不会返回密码或私钥。使用 connection_open 的 hostname: "lab" 建立连接。需要从 MCP 保存或删除主机配置时，使用 advanced profile 下的旧管理工具。

完整字段和默认值见 [config.example.yaml](config.example.yaml)。

串口

先使用 connection_list 查询本机可见串口，然后使用下列参数建立连接：

{
  "transport": "serial",
  "device": "/dev/ttyUSB0",
  "baud_rate": 115200,
  "data_bits": 8,
  "parity": "none",
  "stop_bits": "1"
}

Linux 上运行 MCP 服务的用户必须拥有设备访问权限。通常做法是加入 dialout 组并重新登录：

sudo usermod -aG dialout "$USER"

不要让 MCP stdio 服务在启动时请求 sudo 密码；这会占用标准输入并破坏 MCP 握手。

开发与验证

go test ./...
go vet ./...
go test -race ./pkg/terminal ./pkg/serialmcp ./pkg/mcp

本机 SSH 与串口集成测试均为显式 opt-in，避免默认测试连接设备或使用凭据。相关环境变量定义在 pkg/mcp/terminal_integration_test.go。

发布

推送以 v 开头的版本 tag 会自动创建 GitHub Release，并附带 Linux（amd64、arm64）、macOS（amd64、arm64）和 Windows（amd64）二进制包：

git tag v1.0.0
git push origin v1.0.0

每个压缩包包含 sshmcp、示例配置、双语 README 和许可证。也可以在 GitHub Actions 的 Release 工作流中手动填写 tag 触发发布。

License

See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Cigarliu
• Source: Cigarliu/ssh-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.