使用说明

SSH联络MCP服务器

通过模型上下文协议（MCP）进行状态SSH连接和命令执行

✨ 特性

特性	描述
🔄 有意义的会议	核心功能：外壳状态（当前目录、环境变量、工作目录）在MCP工具调用之间保留。每个命令都在同一个持久shell会话中运行，允许多步工作流。
🔌 MCP服务器模式	与Cursor/Claude Desktop集成，用于执行有状态命令的AI辅助SSH操作
⚙️ SSH配置支持	用途 `~/.ssh/config` 用于主机别名和连接参数
🔐 直接连接	使用用户/主机名/密码/端口直接连接，无需SSH配置
💻 独立CLI模式	用于调试和测试的交互式终端（见下文）

📦 安装

预构建二进制文件

从以下网址下载适用于您平台的最新版本发布页面.

可用平台：

macOS（英特尔x86_64，苹果Silicon aarch64）
Linux（x86_64，aarch64）
Windows（x86_64）

# macOS (Apple Silicon)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-aarch64-apple-darwin.tar.gz
tar -xzf ssh-liaison-mcp-aarch64-apple-darwin.tar.gz

# macOS (Intel)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-x86_64-apple-darwin.tar.gz
tar -xzf ssh-liaison-mcp-x86_64-apple-darwin.tar.gz

# Linux (x86_64)
curl -LO https://github.com/Citizen4our/ssh-liaison-mcp/releases/latest/download/ssh-liaison-mcp-x86_64-unknown-linux-gnu.tar.gz
tar -xzf ssh-liaison-mcp-x86_64-unknown-linux-gnu.tar.gz

从源代码构建

git clone https://github.com/Citizen4our/ssh-liaison-mcp.git
cd ssh-liaison-mcp
cargo build --release

二进制文件将位于 target/release/ssh-liaison-mcp.

🚀 用法

MCP服务器模式（主要用例）

此服务器的主要功能是 有状态SSH会话 -每个SSH连接都维护一个持久的shell会话，在MCP工具调用之间保留状态（当前目录、环境变量等）。这实现了命令相互构建的自然多步骤工作流。

有状态的会议是如何运作的

当您通过以下方式连接到主机时 ssh_connect，建立持久shell会话。所有后续 ssh_run_command 在中执行对该主机的调用 同一shell会话，意思是：

保留当前目录：如果你 cd /var/log 在一个命令中，下一个命令从开始 /var/log
环境变量持续存在：变量设置为 export 在后续命令中保持可用
外壳状态保持不变：历史记录、别名和其他shell状态在调用之间持续存在
高效：无需为每个命令重新连接或重新建立上下文

工作流程示例：

1. ssh_connect("production") → Establishes persistent shell
2. ssh_run_command("production", "cd /var/log") → Changes directory
3. ssh_run_command("production", "pwd") → Returns "/var/log" (state preserved!)
4. ssh_run_command("production", "ls -la") → Lists files in /var/log

用于游标IDE

构建二进制文件：
```
cargo build --release
```

添加到光标设置 (~/.cursor/mcp.json 或光标设置UI）：

{
  "mcpServers": {
    "ssh-liaison": {
      "command": "/absolute/path/to/ssh-liaison-mcp",
      "args": ["serve"]
    }
  }
}

重新启动游标

适用于克劳德桌面

构建二进制文件：
```
cargo build --release
```

添加到Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "ssh-liaison": {
      "command": "/absolute/path/to/ssh-liaison-mcp",
      "args": ["serve"]
    }
  }
}

重新启动克劳德桌面

传统直接连接模式

为了向后兼容：

cargo run -- connect <user> <host> [--port <port>]

🔧 SSH配置

服务器读取 ~/.ssh/config 用于主机别名。这是推荐的连接方式，因为它集中了连接设置。

SSH配置示例

# Simple host alias
Host rpi
    HostName 192.168.1.100
    User pi
    Port 22
    IdentityFile ~/.ssh/id_ed25519

# Production server with custom port
Host production
    HostName prod.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_key

# Development server
Host dev
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/id_rsa

🛠️ MCP工具

当作为MCP服务器运行时，可以使用以下工具：

工具	说明	参数
ssh-connect	连接到远程SSH服务器并建立持久shell会话会话在后续命令调用之间保持状态。	`host_alias` （string）-SSH配置中定义的主机别名
ssh_connect_direct	使用用户、主机名/IP、可选密码和可选端口直接连接到远程SSH服务器。建立持久shell会话它在后续命令调用之间保持状态。身份验证首先尝试SSH密钥，然后尝试密码（如果提供）。	`host_alias` （string）-用于标识此连接的主机别名， `user` （string）-SSH用户名， `hostname` （string）-主机名或IP地址， `password` （字符串，可选）-SSH密码（如果SSH密钥失败或不可用）， `port` （整数，可选）-SSH端口（默认值：22）
ssh_run_命令	在持久shell中执行命令。通过SSH配置或注册的直接配置文件自动连接。空闲/最大超时可配置。	`host`, `command`，可选 `sudo_password`, `timeout_secs`, `max_timeout_secs`
ssh_run_detached	在后台运行一个长命令（tmux或本机）。退货 `job_id`.	`host`, `command`
ssh_job_status	已分离作业的非阻塞状态和新输出。	`host`, `job_id`
ssh_job_wait	阻塞，直到作业完成或超时。	`host`, `job_id`，可选 `timeout_secs`
ssh_job_信号	发送 `int`, `term`，或 `kill` 给一个超然的工人。	`host`, `job_id`, `signal`
ssh_read_log	从日志文件中读取最后N行。需要时自动连接。	`host`, `file_path`, `lines`

重要提示：

有状态（相同的MCP过程）：同一主机的命令共享一个shell会话； cd 并且env持续存在，直到MCP服务器进程重新启动。
自动连接: ssh_run_command、拆卸工具，以及 ssh_read_log 通过自动连接 ~/.ssh/config 或由保存的配置文件 ssh_connect_direct 在相同的过程中。
多进程MCP客户端：每个工具调用都可以在一个新的进程中运行——shell状态不会延续，但自动连接仍然适用于在该进程中注册的SSH配置和直接配置文件。
长命令：更喜欢 ssh_run_detached 当运行时间可能超过命令超时时。
连接方式:
- 使用 ssh_connect 对于基于SSH配置的连接（需要 ~/.ssh/config)
- 使用 ssh_connect_direct 用于无需SSH配置的直接连接
身份验证顺序 （为 ssh_connect_direct):
1. SSH密钥（SSH代理，然后是通用密钥文件）
2. 密码（如果提供且SSH密钥失败）
会话保持：一旦连接，会话将保持活动状态，直到MCP服务器重新启动或明确断开连接
安全：密码在 ssh_connect_direct 通过SSH协议（加密）安全传输。如果可用，首选SSH密钥身份验证。

MCP模式提示示例

配置MCP服务器后，您可以要求AI助手执行SSH操作：

示例1：

User: Connect to rpi and show me the current directory and disk usage

AI回应：

I'll connect to rpi and check the current directory and disk usage for you.

[Connecting to rpi...]

Current directory: /home/pi
Disk usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        15G  5.2G  8.8G  38% /
/dev/mmcblk0p1  253M   49M  204M  20% /boot

示例2：

User: Connect to production and read the last 50 lines from /var/log/nginx/error.log

AI回应：

I'll connect to production and read the last 50 lines from the nginx error log.

[Connecting to production...]

Last 50 lines from /var/log/nginx/error.log:
2024-01-15 10:23:45 [error] 12345#0: *123 connect() failed (111: Connection refused)
2024-01-15 10:24:12 [error] 12345#0: *124 upstream timed out
...

示例3：

User: Connect directly to 192.168.88.63 as user pi and show disk usage

AI回应：

I'll connect directly to 192.168.88.63 as user pi and check the disk usage.

[Connecting to 192.168.88.63 using SSH keys...]

Disk usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        15G  5.2G  8.8G  38% /
/dev/mmcblk0p1  253M   49M  204M  20% /boot

示例3b（带密码）：

User: Connect to 192.168.88.63 as user admin with password mypass123 and check uptime

AI回应：

I'll connect to 192.168.88.63 as user admin and check the system uptime.

[Connecting to 192.168.88.63...]
[SSH key authentication failed, trying password...]

System uptime: 5 days, 12 hours, 30 minutes

示例4：

User: Check system uptime and memory usage on the dev server

AI回应：

I'll check the system uptime and memory usage on the dev server.

[Connecting to dev...]

System uptime: 15 days, 3 hours, 22 minutes
Memory usage:
              total        used        free      shared  buff/cache   available
Mem:           7.8G        2.1G        3.2G        128M        2.5G        5.4G
Swap:          2.0G          0B        2.0G

示例5：

User: Show me running processes and check if nginx service is running on production

AI回应：

I'll check the running processes and verify if nginx is running on production.

[Connecting to production...]

Nginx service status: active (running)
Top processes by CPU:
  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
 1234 nginx     20   0  123456   4567   1234 S   2.3   0.1   0:05:23 nginx
 5678 app       20   0  234567   8901   2345 S   1.8   0.2   0:12:45 app
...

状态会话示例

此示例演示了如何在命令之间保留状态：

User: Connect to rpi, navigate to /var/log, and show me the last 10 lines of syslog

AI回应：

I'll connect to rpi, navigate to /var/log, and show you the last 10 lines of syslog.

[Connecting to rpi...]
[Changing directory to /var/log...]

Last 10 lines of syslog:
Jan 15 10:23:45 rpi systemd[1]: Started Network Manager.
Jan 15 10:24:12 rpi sshd[1234]: Accepted publickey for pi from 192.168.1.50
...

幕后发生了什么：

ssh_connect("rpi") -已建立持久shell会话
ssh_run_command("rpi", "cd /var/log") -已更改目录（状态已保存）
ssh_run_command("rpi", "tail -n 10 syslog") -执行自 /var/log （国家保存！）

第二个命令从以下位置自动启动 /var/log 因为shell状态是从上一个命令中保留的。

独立CLI模式（用于调试）

用于测试和调试的交互式终端模式。可用于手动排除连接问题或测试命令。

连接方式

1.使用SSH配置别名

# Connect immediately using alias from ~/.ssh/config
cargo run -- cli --host rpi
# or
./target/release/ssh-liaison-mcp cli --host rpi

2.通过命令行直接连接

# Direct connection with SSH keys (default port 22)
cargo run -- cli --user pi --hostname 192.168.1.100

# Direct connection with custom port
cargo run -- cli --user pi --hostname 192.168.1.100 --port 2222

# Direct connection with password authentication
cargo run -- cli --user pi --hostname 192.168.1.100 --password mypassword

# Direct connection with password and custom port
cargo run -- cli --user pi --hostname 192.168.1.100 --password mypassword --port 2222

连接示例

# Example 1: Connect via SSH config
cargo run -- cli --host production

# Example 2: Direct connection to Raspberry Pi
cargo run -- cli --user pi --hostname 192.168.1.100

# Example 3: Direct connection with password to custom port
cargo run -- cli --user admin --hostname server.example.com --password secret --port 2222

# Example 4: Interactive mode - connect later
cargo run -- cli
ssh> connect dev-server
[dev-server]> uname -a
[dev-server]> exit

🔐 认证

为了 `ssh_connect` （SSH配置）

服务器尝试按以下顺序进行身份验证：

SSH代理 （如果可用）
身份文件 从SSH配置
常见SSH密钥 （按顺序）：
- ~/.ssh/id_ed25519
- ~/.ssh/id_rsa
- ~/.ssh/id_ecdsa
- ~/.ssh/id_dsa

为了 `ssh_connect_direct` （直接连接）

SSH密钥 （顺序同上）
密码（如果提供了SSH密钥，但SSH密钥失败或不可用）

⚠️ 安全说明

建议只读操作：这些工具包括关于破坏性操作的警告
密码处理：计划提供Sudo密码启发支持，但尚未完全实施
无密码记录：密码从不被记录或公开

🧪 发展

# Run in development mode
cargo run -- cli --host <your-host>

# Build release
cargo build --release

# Run tests
cargo test

# Run lints
cargo clippy --all-targets -- -D warnings

# Format code
cargo fmt

📊 日志记录

服务器通过以下方式使用结构化日志记录 tracing 机箱。通过以下方式控制日志的冗长程度：

命令行标志

# Default (warnings only)
ssh-liaison-mcp serve

# Info level (-v)
ssh-liaison-mcp -v serve

# Debug level (-vv)
ssh-liaison-mcp -vv serve

# Trace level (-vvv)
ssh-liaison-mcp -vvv serve

环境变量

# Set log level via RUST_LOG
RUST_LOG=debug ssh-liaison-mcp serve

# Target specific modules
RUST_LOG=ssh_liaison_mcp=debug ssh-liaison-mcp serve

# Multiple targets
RUST_LOG=ssh_liaison_mcp::ssh=trace,ssh_liaison_mcp::mcp=debug ssh-liaison-mcp serve

📋 TODO/未来改进

基础设施和分销

[x] CI/CD管道（GitHub操作）
- [x] push/PR的自动化测试
- [x] 绒毛和格式检查（剪贴、生锈）
- [x] 为多个平台（Linux、macOS、Windows）构建
- [x] 自动发布工作流程
[x] 发布自动化
- [x] GitHub创建发布的操作工作流
- [x] 主要平台的自动二进制构建
- [x] GitHub发布预构建二进制文件
- []版本碰撞自动化
[ ] Crates.io出版物
- [x] 准备板条箱元数据（描述、关键字、类别）
- []添加板条箱文档
- []发布到crates.io

特性

[ ] Sudo密码获取
- []未提供密码时MCP提示（交互式启发）
- []会话期间的密码缓存
[ ] 会话管理
- [ ] ssh_disconnect 显式关闭会话的工具
- [ ] ssh_list_sessions 显示活动连接的工具
- []超时时自动清理会话
- []会话健康检查和重新连接
[ ] 增强的错误处理
- []更好的带有上下文的错误消息
- []连接重试逻辑
- []巧妙地处理网络中断
- []会话恢复机制
[ ] 文件操作
- [ ] ssh_read_file 读取远程文件的工具
- [ ] ssh_write_file 工具（带安全检查）
- [ ] ssh_list_directory 目录列表工具
- []支持二进制文件传输
[ ] 监测和可观察性
- []连接状态监控
- []可选详细日志记录模式

代码质量

[ ] 测试
- [x] SSH配置解析的单元测试
- []MCP工具的集成测试
- []模拟SSH服务器进行测试
- []CLI模式测试
[ ] 文档
- []API文件（rustdoc）
- []架构文档
- []贡献指南
- []安全最佳实践指南
[x] 代码改进
- [x] 重构错误处理模式
- [x] 添加全面的日志记录（跟踪）
- []性能优化
- []代码覆盖率改进

平台支持

[x] 跨平台二进制发布
- [x] Linux（x86_64，ARM64）
- [x] macOS（英特尔、苹果硅）
- [x] Windows（x86_64）
[ ] 包装经理
- []适用于macOS的自制配方
- []Arch Linux的AUR软件包

增强的安全性

[ ] 安全审计
- []依赖关系安全扫描
- []代码安全审查
- []渗透测试注意事项
[ ] 访问控制
- []可选主机列表/域名列表
- []命令白名单/黑名单
- []连接速率限制

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

使用说明

SSH联络MCP服务器

✨ 特性

📦 安装

预构建二进制文件

从源代码构建

🚀 用法

MCP服务器模式（主要用例）

有状态的会议是如何运作的

用于游标IDE

适用于克劳德桌面

传统直接连接模式

🔧 SSH配置

SSH配置示例

🛠️ MCP工具

MCP模式提示示例

状态会话示例

独立CLI模式（用于调试）

连接方式

连接示例

🔐 认证

为了 ssh_connect （SSH配置）

为了 ssh_connect_direct （直接连接）

⚠️ 安全说明

🧪 发展

📊 日志记录

命令行标志

环境变量

📋 TODO/未来改进

基础设施和分销

特性

代码质量

平台支持

增强的安全性

📄 许可证

相关 MCP

SSH远程命令执行MCP服务器

SSH命令执行服务器

SSH MCP服务器

SSH客户端服务器

浏览器自动化服务

Gemini MCP 服务器

为了 `ssh_connect` （SSH配置）

为了 `ssh_connect_direct` （直接连接）