内容
# MCP SSH 会话 - 重启
一个MCP（模型上下文协议）服务器，使AI代理能够建立和管理持久的SSH会话。
## 功能
- **智能命令执行** - 如果达到超时时间，则自动切换到异步模式
- **持久会话** - 跨命令重用SSH连接
- **异步命令** - 长任务的非阻塞执行
- **SSH配置支持** - 读取`~/.ssh/config`以获取别名、端口、密钥
- **多主机** - 同时管理多个主机的连接
- **网络设备** - 启用Cisco、Juniper、MikroTik等的模式处理
- **Sudo支持** - Unix/Linux主机的自动密码处理
- **文件操作** - 通过SFTP（sudo回退）读写远程文件
- **命令中断** - 发送Ctrl+C停止运行的命令
- **线程安全** - 适用于并发操作
- **异步原生** - 内置支持asynio
## 快速入门
### 📦 从`mcp-ssh-session`迁移
该项目是原始[`devnullvoid/mcp-ssh-session`](https://github.com/devnullvoid/mcp-ssh-session)的直接替代品。要迁移：
1. **替换包名** - `mcp-ssh-session` → `mcp-ssh-reloaded`
2. **环境变量完全继承** - 所有`OVRD_*`和`MCP_SSH_*`环境变量均按原样工作
3. **就是这样** - 重新连接即可完成
<table>
<tr><th>之前（旧）</th><th>之后（新）</th></tr>
<tr><td>
```json
{
"mcpServers": {
"ssh-session": {
"command": "uvx",
"args": ["mcp-ssh-session", "serve", "mcp"]
}
}
}
```
</td><td>
```json
{
"mcpServers": {
"ssh-session": {
"command": "uvx",
"args": ["mcp-ssh-reloaded", "serve", "mcp"]
}
}
}
```
</td></tr>
</table>
### 安装
```bash
uvx mcp-ssh-reloaded
```
### 开发
```bash
uv venv
source .venv/bin/activate
uv pip install -e .
```
### 命令行界面
```bash
# MCP服务器（默认）
mcp-ssh-reloaded serve mcp
# 直接执行（无MCP）
mcp-ssh-reloaded exec myserver "uname -a" -u admin
# 列出/关闭会话
mcp-ssh-reloaded list
mcp-ssh-reloaded close-all
```
### MCP客户端配置
**Claude 代码 / 桌面版** (`~/.claude.json` 或 `claude_desktop_config.json`)：
```json
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh-reloaded", "serve", "mcp"],
"env": {}
}
}
}
```
### 快速示例
```json
// SSH配置别名
{ "host": "myserver", "command": "uptime" }
// 显式参数
{ "host": "example.com", "username": "user", "command": "ls -la", "port": 2222 }
// 网络设备（Cisco启用模式）
{ "host": "router", "username": "admin", "enable_password": "secret", "command": "show run" }
// 带有sudo的Unix
{ "host": "server", "username": "ops", "sudo_password": "secret", "command": "systemctl restart nginx" }
```
---
> **完整API参考：** [API-DOCS.md](./API-DOCS.md) - 所有类型、所有方法、所有MCP工具、错误处理、服务器配置可调。
## SSH配置
`~/.ssh/config`被自动读取：
```
Host myserver
HostName example.com
User myuser
Port 2222
IdentityFile ~/.ssh/id_rsa
```
然后使用`"host": "myserver"` - 其余部分为您解析。
## 凭证隐藏（OVRD_*）
对于生产环境，将真实凭证存储在环境变量中，以便AI代理只看到别名：
| 变量 | 描述 |
| -------------------------- | ----------------------- |
| `OVRD_{alias}_HOST` | 真实主机名或IP地址 |
| `OVRD_{alias}_PORT` | SSH端口 |
| `OVRD_{alias}_USER` | SSH用户名 |
| `OVRD_{alias}_PASS` | SSH密码 |
| `OVRD_{alias}_KEY` | SSH私钥路径 |
| `OVRD_{alias}_SUDO_PASS` | Sudo密码 |
| `OVRD_{alias}_ENABLE_PASS` | 启用密码 |
**示例配置：**
```json
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh-reloaded", "serve", "mcp"],
"env": {
"OVRD_prod_db_HOST": "192.168.1.100",
"OVRD_prod_db_USER": "admin",
"OVRD_prod_db_PASS": "secret123",
"OVRD_prod_db_SUDO_PASS": "sudopass"
}
}
}
}
```
代理使用`"host": "prod_db"` - 永远不会看到真实的IP地址或密码。
## 配置
### 超时和服务器设置
所有可调参数都位于`ServerConfig`中。值按优先级解析：
1. **构造函数kwargs**（最高）
2. **`MCP_SSH_*`环境变量**
3. **默认值**（最低）
| 环境变量 | 默认值 | 描述 |
| ---------------------------------------- | --------------------------- | ----------------------------------- |
| `MCP_SSH_DEFAULT_TIMEOUT` | `30` | 命令超时（秒） |
| `MCP_SSH_MAX_TIMEOUT` | `300` | 超时上限 |
| `MCP_SSH_CONNECT_TIMEOUT` | `30` | SSH连接超时 |
| `MCP_SSH_MAX_WORKERS` | `10` | 线程池大小 |
| `MCP_SSH_MAX_FILE_BYTES` | `2097152` | 最大文件读写（2 MB） |
| `MCP_SSH_MAX_OUTPUT_BYTES` | `10485760` | 最大命令输出（10 MB） |
| `MCP_SSH_INTERACTIVE_MODE` | `true` | 启用PTY终端仿真 |
| `MCP_SSH_PTY_AWARE_VALIDATION` | `false` | 放松PTY检查验证 |
| `MCP_SSH_MIKROTIK_AUTO_PAGING` | `true` | 自动处理MikroTik分页 |
| `MCP_SSH_TERMINAL_WIDTH` | `100` | PTY列 |
| `MCP_SSH_TERMINAL_HEIGHT` | `24` | PTY行 |
| `MCP_SSH_LOG_DIR` | `/tmp/mcp_ssh_session_logs` | 日志目录 |
| `MCP_SSH_BACKGROUND_MONITOR_MAX_TIMEOUT` | `300` | 后台监视器最大超时 |
| `MCP_SSH_NORMAL_IDLE_TIMEOUT` | `2` | 普通空闲超时（秒） |
| `MCP_SSH_PACKAGE_MANAGER_IDLE_TIMEOUT` | `10` | 包管理器空闲超时 |
| `MCP_SSH_ASYNC_DEFAULT_TIMEOUT` | `30` | 异步命令默认超时 |
### 通过CLI（服务模式）
```bash
mcp-ssh serve mcp --default-timeout 60 --max-workers 20
mcp-ssh serve http --port 8080 --interactive-mode false
mcp-ssh serve sse --port 9000 --connect-timeout 15
```
### 通过API
```python
from mcp_ssh_reloaded import SSHService, ServerConfig
svc = SSHService(config=ServerConfig(default_timeout=60, max_timeout=600))
```
## 工作原理
命令在持久的交互式shell中运行：
- **目录持久化**：`cd /tmp` 保持在 `/tmp` 以供下一个命令使用
- **环境变量持久化**：`export FOO=bar` 在各个命令中可见
- **提示符检测**：通过捕获的提示符或空闲超时（2秒）检测完成
- **会话恢复**：卡住的shell在重复的提示符检测失败后自动重置
## 文档
| 文档 | 主题 |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| [API-DOCS.md](./API-DOCS.md) | 完整API参考 - 类型、SSHService方法、MCP工具、错误模型 |
| [docs/AGENT_GUIDE.md](./docs/AGENT_GUIDE.md) | **代理提示** - 正确使用工具的模式、异步处理 |
| [docs/ASYNC_COMMANDS.md](./docs/ASYNC_COMMANDS.md) | 智能执行和异步命令生命周期 |
| [docs/INTERACTIVE_MODE.md](./docs/INTERACTIVE_MODE.md) | 终端仿真、屏幕快照、按键发送 |
| [docs/SAFETY_PROTECTIONS.md](./docs/SAFETY_PROTECTIONS.md) | 限制、超时、会话恢复、错误处理 |
| [docs/DOCKER.md](./docs/DOCKER.md) | 使用Docker运行 |
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE)。
## 分叉
[devnullvoid/mcp-ssh-session](https://github.com/devnullvoid/mcp-ssh-session) 的分叉，由 [AmritaConstant](https://github.com/AmritaBot) 进行重大重构。
