# Ssh Mcp Server

> A powerful SSH/SFTP MCP server with multi-instance support and intelligent configuration discovery

- **Type:** MCP server
- **Install:** `agentstack add mcp-cigarliu-ssh-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Cigarliu](https://agentstack.voostack.com/s/cigarliu)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Cigarliu](https://github.com/Cigarliu)
- **Source:** https://github.com/Cigarliu/ssh-mcp-server

## Install

```sh
agentstack add mcp-cigarliu-ssh-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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` 或更高版本。

```bash
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 客户端中配置标准输入输出服务：

```json
{
  "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 或运行交互程序时：

```text
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` 读取原始数据；串口没有屏幕投影。

## 配置

最小配置示例：

```yaml
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` 查询本机可见串口，然后使用下列参数建立连接：

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

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

```bash
sudo usermod -aG dialout "$USER"
```

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

## 开发与验证

```bash
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）二进制包：

```bash
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](https://github.com/Cigarliu)
- **Source:** [Cigarliu/ssh-mcp-server](https://github.com/Cigarliu/ssh-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cigarliu-ssh-mcp-server
- Seller: https://agentstack.voostack.com/s/cigarliu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.