mcp-ssh交互式

Name: mcp-ssh交互式
Author: qnxqnxqnx

作者：qnxqnxqnx2 星标更新：2025-11-05

安装使用来源：spider==github.com

项目介绍

MCP SSH Interactive

一个通过tmux实现AI代理完全交互式SSH会话并执行命令（如同人类操作员）的MCP（模型上下文协议）服务器。

功能

通过tmux进行交互式SSH：真实的终端行为、提示符、Ctrl+C、历史记录。
持久会话：会话在工具调用之间存活；可重新连接。
多个并发连接：并行管理许多服务器。
完整的输出捕获：可靠地检索终端缓冲区。
异步命令 + 轮询：长任务的发射和检查模式。
特定于服务器的信息：通过markdown文件提供每台服务器的自定义指令和命令。

要求

Python：3.9+
tmux：2.6+ (tmux -V)
- 安装：macOS上使用brew install tmux，Linux上使用apt install tmux / yum install tmux / pacman -S tmux
OpenSSH客户端：7.0+
操作系统：Linux或macOS

安装

对于最终用户（仅想使用MCP服务器）：

# 克隆仓库
git clone https://github.com/yourusername/mcp-ssh-interactive.git
cd mcp-ssh-interactive

# 使用pip安装
pip install .

或者使用pipx创建隔离环境（推荐）：

# 使用pipx安装
pipx install .

对于开发者（正在编写代码）：

# 克隆仓库
git clone https://github.com/yourusername/mcp-ssh-interactive.git
cd mcp-ssh-interactive

# 在可编辑模式下安装
pip install -e .

注意：此包尚未发布到PyPI，因此需要从源码安装。

配置

创建~/.mcp-ssh-interactive/config.yml文件，包含您的SSH目标：

connections:
  my-server:
    host: 192.168.1.100
    user: username
    key_path: ~/.ssh/id_rsa
    port: 22
    description: 我的远程服务器
    info_file: my-server.md  # 可选：指向特定于服务器信息文件的路径
  prod-db:
    host: db.example.com
    user: deploy
    key_path: ~/.ssh/id_ed25519
    port: 22
    description: 生产数据库主机（只读）
  test-server:
    host: test.example.com
    user: demo
    password: mypassword
    port: 22
    description: 使用密码认证的测试服务器

注意事项：

必须提供key_path或password用于身份验证
强烈建议使用key_path以提高安全性
如果使用key_path，必须存在且可读；典型权限chmod 600
必须存在~/.mcp-ssh-interactive/config.yml；如果缺失或无效，服务器将以明确错误退出
info_file（可选）：指向包含特定于服务器指令和信息的markdown文件的路径。支持：
- 相对路径（例如，my-server.md）- 相对于~/.mcp-ssh-interactive/info/解析
- 以~开头的绝对路径（例如，~/custom/path/server.md）
- 以/开头的绝对路径（例如，/tmp/server.md）

注意：必须至少提供key_path或password之一。强烈建议使用key_path以提高安全性。

特定于服务器的信息

您可以通过创建markdown文件并在配置中引用它们来为每个服务器提供特定的指令、命令和重要信息。这使AI代理能够使用与特定环境相关的特定工具、方法和工作流程与服务器交互。您还可以在这些文件中记录常规任务和程序，使AI代理能够快速理解服务器的独特要求，并根据用户请求成功执行任务。

示例：

当为服务器定义了info_file时，用户可以简单地提到诸如“重启应用程序”或“部署最新版本”的任务，而AI代理将确切知道要执行哪些命令以及遵循哪些程序。

在~/.mcp-ssh-interactive/info/prod-web-server.md创建一个markdown文件：

# 生产Web服务器

## 认证与访问

- 根访问：`sudo su -`（密码：`prod_admin_2024`）
- 应用程序用户：`sudo -u webapp bash`（所有应用命令所需）

## 密钥路径

- 应用程序：`/opt/webapp/current`
- 配置：`/opt/webapp/config/production.yml`
- 日志：`/var/log/webapp/`

## 常见任务

### 重启应用程序
sudo systemctl restart webapp

### 部署新版本
cd /opt/webapp/releases
sudo -u webapp /opt/webapp/bin/deploy.sh --version latest
curl -s http://localhost:8080/health | jq .

### 检查应用程序状态
sudo systemctl status webapp
journalctl -u webapp -n 50 --no-pager

### 查看日志
tail -f /var/log/webapp/application.log

### 数据库备份
sudo /usr/local/bin/backup-db.sh production

## 重要约束

- 只读数据库：此服务器连接到只读副本。永远不要尝试写操作。
- 维护窗口：仅在UTC时间02:00-04:00之间部署
- 监控：https://monitoring.example.com/d/webapp-prod

在配置中引用它：

connections:
  my-server:
    host: 192.168.1.100
    user: username
    key_path: ~/.ssh/id_rsa
    info_file: my-server.md  # 相对路径（解析为 ~/.mcp-ssh-interactive/info/my-server.md）

信息文件路径解析：

相对路径（例如，my-server.md）：相对于~/.mcp-ssh-interactive/info/解析
以~开头的路径（例如，~/custom/path/server.md）：视为绝对路径
以/开头的路径（例如，/tmp/server.md）：视为绝对路径

特定于服务器的信息从info_file可供使用该服务器配置的所有会话使用。

启动MCP服务器

服务器通过标准I/O运行，并由您的MCP客户端启动。您也可以手动启动它：

mcp-ssh-interactive

如果未安装tmux或配置无效，服务器将以错误退出。

与MCP客户端一起使用（通用JSON配置）

在您的MCP客户端配置中添加此服务器条目。通用结构如下：

{
  "mcpServers": {
    "mcp-ssh-interactive": {
      "command": "mcp-ssh-interactive"
    }
  }
}

不同的MCP客户端可能使用不同格式和位置的配置文件。请查阅您特定MCP客户端的相关文档，确定在哪里以及如何添加MCP服务器配置。

添加后，重启或重新加载您的客户端，以便它可以发现新的服务器。

典型工作流

当此MCP服务器对代理可用时，您可以简单地让代理打开my-server服务器上的会话并描述您需要执行的任务。代理通常会自动检查配置文件中的可用服务器列表，找到命名服务器，打开新会话，并执行info_file字段中指定的任何初始化任务（如果已配置）。

可用工具

服务器提供了以下工具：

list_available_configs：列出来自~/.mcp-ssh-interactive/config.yml的可用连接配置。
open_connection：打开SSH连接并开始带有日志记录的tmux会话。
list_connections：列出活动连接及其状态。
execute_command：在远程服务器上执行命令（立即返回）。
get_terminal_output：从远程会话中检索当前终端输出。
interrupt_command：发送Ctrl+C中断正在运行的命令。
close_connection：关闭连接并终止tmux会话。
get_server_info：从配置的info_file（如果有）中检索特定于服务器的信息。

文件结构

所有文件存储在~/.mcp-ssh-interactive/：

~/.mcp-ssh-interactive/
├── config.yml           # SSH连接配置
├── state.json           # 活动会话状态
├── logs/                # 会话日志
│   └── <session_name>.log
└── info/                # 特定于服务器的信息文件
    └── <server-name>.md

文件：

config.yml：包含主机、用户、密钥和可选info_file引用的SSH连接配置
state.json：跟踪活动会话、其tmux名称、日志文件路径和时间戳
logs/：包含会话日志的目录（每个活动会话一个）
- tmux从连接打开时开始将面板输出管道到这些文件
- 文件创建时具有目录权限700；根据需要旋转/修剪
info/：特定于服务器的信息文件目录（markdown格式）
- 通过config.yml中的info_file字段引用
- 可以使用相对路径（例如，my-server.md）或绝对路径

所有文件都位于运行MCP服务器的机器上（您的工作站）。

故障排除

“tmux未安装或不可访问”
- 安装tmux（macOS上使用brew install tmux，Linux上使用apt/yum/pacman），并确保它在$PATH中。
“找不到配置文件”或“配置为空”
- 如上所示创建~/.mcp-ssh-interactive/config.yml；验证正确的YAML。
“密钥文件未找到”或SSH失败（权限被拒绝，主机密钥验证）
- 检查key_path是否存在且具有chmod 600。
- 确保ssh -i <key> user@host在MCP之外正常工作。
- 通过首次手动SSH或配置known_hosts预接受主机密钥。
没有写入日志
- 确认~/.mcp-ssh-interactive/logs/存在且可写；服务器会自动创建它。
- 确认您的session_name并检查匹配的日志路径。
调用get_server_info时出现“信息文件未找到”错误
- 检查配置中的info_file路径是否正确。
- 对于相对路径，确保文件存在于~/.mcp-ssh-interactive/info/中。
- 验证文件具有适当的读取权限。

安全考虑

⚠️ 安全警告

此MCP服务器授予AI代理在经过身份验证的用户权限级别下的完全控制权。
如果以root登录，AI代理可以执行任何root可以执行的命令，包括破坏性操作
AI代理可以读取、修改或删除文件，安装/卸载软件，更改配置，并执行任何其他系统操作
没有内置的安全措施防止AI代理做出不可逆的更改
execute_command工具包括指示AI代理在执行更改状态的命令前请求确认的说明，但这只是指导——不是强制执行。始终保持警惕。
始终使用最低权限账户；尽可能避免使用root或管理员账户。
清晰定义给AI代理的任务边界（只读与允许修改）。
在没有极端谨慎和明确任务边界的情况下，绝不在生产系统上使用此服务器。

此工具强大且方便，但伴随着巨大的权力而来的是巨大的责任。始终明确AI代理被允许做什么。

文件和数据安全：

绝不将~/.mcp-ssh-interactive/config.yml或私钥提交到源代码控制。
将~/.mcp-ssh-interactive/logs/*.log视为敏感；它们可能包含命令输出。
如果包含密码或敏感信息，则将~/.mcp-ssh-interactive/info/*.md视为敏感。

开发

运行简单的集成检查：

python tests/test_integration.py

许可证

MIT