SSH联络MCP服务器

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

![CI](https://github.com/Citizen4our/ssh-liaison-mcp/actions/workflows/ci.yml) ![Release](https://github.com/Citizen4our/ssh-liaison-mcp/releases) ![Rust](https://www.rust-lang.org/) ![License: MIT](https://opensource.org/licenses/MIT)

______________________________________________________________________

✨ 特性

特性	描述
🔄 有意义的会议	核心功能：外壳状态（当前目录、环境变量、工作目录）在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   [--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会话。当前目录、环境变量和shell状态从以前的命令中保留。	`host` （string）-主机别名， `command` （string）-要执行的命令
ssh_read_log	使用持久shell会话从日志文件中读取最后N行。	`host` （string）-主机别名， `file_path` （string）-日志文件的路径， `lines` （整数）-要读取的行数

重要提示：

有状态的：同一主机的所有命令都在同一持久shell会话中运行
连接方式:

- 使用 ssh_connect 对于基于SSH配置的连接（需要 ~/.ssh/config) - 使用 ssh_connect_direct 用于无需SSH配置的直接连接

身份验证顺序 （为 ssh_connect_direct):

1. SSH密钥（SSH代理，然后是通用密钥文件） 1. 密码（如果提供且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 

# 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密码获取

- \[\]实现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 Liaison MCP

快速接入

详细介绍

SSH联络MCP服务器

✨ 特性

📦 安装

预构建二进制文件

从源代码构建

🚀 用法

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

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

用于游标IDE

适用于克劳德桌面

传统直接连接模式

🔧 SSH配置

SSH配置示例

🛠️ MCP工具

MCP模式提示示例

状态会话示例

独立CLI模式（用于调试）

连接方式

连接示例

🔐 认证

对于 ssh_connect （SSH配置）

对于 ssh_connect_direct （直接连接）

⚠️ 安全说明

🧪 发展

📊 日志记录

命令行标志

环境变量

📋 TODO/未来改进

基础设施和分销

特性

代码质量

平台支持

增强的安全性

📄 许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

对于 `ssh_connect` （SSH配置）

对于 `ssh_connect_direct` （直接连接）