MCP SSH互动
MCP（模型上下文协议）服务器，使AI代理能够运行完全交互式的SSH会话（通过tmux），并像人类操作员一样执行命令。
特性
- 通过tmux进行交互式SSH：真实的终端行为、提示、Ctrl+C、历史。
- 持续会话：会话在工具调用中存活；可重新连接。
- 多个并发连接：并行管理许多服务器。
- 完成输出捕获：可靠地检索终端缓冲区。
- 异步命令+轮询：长任务的射击和检查模式。
- 服务器特定信息：通过markdown文件为每台服务器提供自定义指令和命令。
需求
- python: 3.9+
- 终端复用器: 2.6+ (
tmux -V)
- 安装： brew install tmux 在macOS上， apt install tmux / yum install tmux / pacman -S tmux 在Linux上
- OpenSSH客户端: 7.0+
- 操作系统：Linux或macOS
安装
面向终端用户 （只想使用MCP服务器）：
# Clone the repository
git clone https://github.com/yourusername/mcp-ssh-interactive.git
cd mcp-ssh-interactive
# Install with pip
pip install .或者在隔离环境中使用pipx（推荐）：
# Install with pipx
pipx install .对于开发者 （编写代码）：
# Clone the repository
git clone https://github.com/yourusername/mcp-ssh-interactive.git
cd mcp-ssh-interactive
# Install in editable mode
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: My remote server
info_file: my-server.md # Optional: path to server-specific info file
prod-db:
host: db.example.com
user: deploy
key_path: ~/.ssh/id_ed25519
port: 22
description: Production database host (read-only)
test-server:
host: test.example.com
user: demo
password: mypassword
port: 22
description: Test server with password authentication笔记：
- 要么
key_path或password必须提供身份验证 key_path强烈推荐password出于安全考虑- 如果使用
key_path，它必须存在并且可读；典型权限chmod 600 ~/.mcp-ssh-interactive/config.yml是必需的；如果丢失或无效，服务器将退出并显示明确的错误info_file（可选）：包含服务器特定指令和信息的markdown文件的路径。看 服务器特定信息 在......下面
模式（非正式）：
- 连接：连接名称映射→ 对象
- 主机 （字符串，必填） - 用户 （字符串，必填） - key_path （字符串，可选，但建议使用； ~ 扩大；已验证存在） - 密码 （字符串，可选；需要此或 key_path) - 端口 （int，默认值 22) - 描述 （字符串，可选） - 信息文件 （字符串，可选）：带有服务器特定信息的markdown文件的路径。支持： - 相对路径（例如。， my-server.md)-相对于 ~/.mcp-ssh-interactive/info/ - 以开头的绝对路径 ~ （例如。， ~/custom/path/server.md) - 以开头的绝对路径 / （例如。， /tmp/server.md)
注：至少有一个 key_path 或 password 必须提供。使用 key_path 出于安全考虑，强烈建议使用。
服务器特定信息
您可以通过创建markdown文件并在配置中引用它们，为每台服务器提供特定于服务器的说明、命令和重要信息 info_file 现场。这使得AI代理能够使用与特定环境相关的特定工具、方法和工作流与服务器进行交互。您还可以在这些文件中记录日常任务和程序，使AI代理能够快速了解服务器的独特要求，并根据用户请求成功执行任务。
例子：
当A info_file 当为服务器定义时，用户可以简单地提及“重新启动应用程序”或“部署最新版本”等任务，AI代理将确切地知道要执行哪些命令以及要为该特定服务器遵循哪些程序。
- 在以下位置创建markdown文件
~/.mcp-ssh-interactive/info/prod-web-server.md:
# Production Web Server
## Authentication & Access
- Root access: `sudo su -` (password: `prod_admin_2024`)
- Application user: `sudo -u webapp bash` (required for all app commands)
## Key Paths
- Application: `/opt/webapp/current`
- Configuration: `/opt/webapp/config/production.yml`
- Logs: `/var/log/webapp/`
## Common Tasks
### Restart Application
sudo systemctl restart webapp
### Deploy New Version
cd /opt/webapp/releases
sudo -u webapp /opt/webapp/bin/deploy.sh --version latest
curl -s http://localhost:8080/health | jq .
### Check Application Status
sudo systemctl status webapp
journalctl -u webapp -n 50 --no-pager
### View Logs
tail -f /var/log/webapp/application.log
### Database Backup
sudo /usr/local/bin/backup-db.sh production
## Important Constraints
- Read-only database: This server connects to a read-only replica. Never attempt write operations.
- Maintenance window: Deployments only between 02:00-04:00 UTC
- Monitoring: 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 # Relative path (resolved to ~/.mcp-ssh-interactive/info/my-server.md)信息文件路径解析：
- 相对路径 （例如。，
my-server.md)：相对于解决~/.mcp-ssh-interactive/info/ - 以开头的路径
~（例如。，~/custom/path/server.md)：被视为绝对路径 - 以开头的路径
/（例如。，/tmp/server.md)：被视为绝对路径
来自的服务器特定信息 info_file 可用于使用该服务器配置的所有会话。
启动MCP服务器
服务器通过stdio运行，由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_config：列出可用的连接配置
~/.mcp-ssh-interactive/config.yml. - 开放式连接：打开SSH连接并启动带有日志记录的tmux会话。
- list_connections：列出活动连接及其状态。
- execute_命令：在远程服务器上执行命令（立即返回）。
- get_terminal_output：从远程会话检索当前终端输出。
- 中断命令：发送Ctrl+C以中断正在运行的命令。
- close_connection：关闭连接并终止tmux会话。
- get_server_info：从配置的服务器检索特定于服务器的信息
info_file（如果可用）。
文件结构
所有文件都存储在 ~/.mcp-ssh-interactive/:
~/.mcp-ssh-interactive/
├── config.yml # SSH connection configurations
├── state.json # Active session state
├── logs/ # Session logs
│ └── .log
└── info/ # Server-specific info files
└── .md文件夹：
- config.yml：SSH连接配置，包括主机、用户、密钥和可选配置
info_file参考文献 - state.json：跟踪活动会话、其tmux名称、日志文件路径和时间戳
- 日志/：包含会话日志的目录（每个活动会话一个）
- 从连接打开的那一刻起，tmux管道窗格输出到这些文件 - 文件是使用目录权限创建的 700；根据需要旋转/修剪
- 信息/：服务器特定信息文件目录（markdown格式）
- 通过引用 info_file config.yml中的字段 - 可以使用相对路径（例如。， my-server.md)或绝对路径
所有文件都是运行MCP服务器的机器（您的工作站）的本地文件。
故障排除
- “tmux未安装或无法访问”
- 安装tmux(brew install tmux 在macOS上， apt/yum/pacman 在Linux上），并确保它在 $PATH.
- “找不到配置文件”或“配置为空”
- 创建 ~/.mcp-ssh-interactive/config.yml 如上所示；验证正确的YAML。
- “找不到密钥文件”或SSH失败（权限被拒绝，主机密钥验证）
- 检查 key_path 存在并具有 chmod 600. - 确保 ssh -i 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代理可以执行 任何命令 该根可以，包括破坏性操作 - 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许可证
麻省理工学院