内容
# MCP SSH 会话
一个MCP（模型上下文协议）服务器，允许AI代理建立和管理持久的SSH会话。
## 功能特点
- **智能命令执行** — 如果达到超时时间，则自动切换到异步模式
- **持久会话** — 在多个命令之间重用SSH连接
- **异步命令** — 非阻塞执行适用于长时间运行的任务
- **SSH配置支持** — 读取 `~/.ssh/config` 中的别名、端口、密钥
- **多主机** — 同时管理多个主机的连接
- **网络设备** — 启用思科、Juniper、MikroTik等设备的模式处理
- **Sudo支持** — Unix/Linux主机的自动密码处理
- **文件操作** — 通过SFTP（sudo回退）读写远程文件
- **命令中断** — 发送Ctrl+C停止正在运行的命令
- **线程安全** — 适用于并发操作
## 快速入门
### 安装
```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 }
// 网络设备（思科启用模式）
{ "host": "router", "username": "admin", "enable_password": "secret", "command": "show run" }
// Unix启用sudo
{ "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地址或密码。
## 工作原理
命令在持久的交互式shell中运行：
- **目录持久化**：`cd /tmp` 保持在 `/tmp` 以便下一个命令
- **环境变量持久化**：`export FOO=bar` 在多个命令中可见
- **提示检测**：通过捕获的提示或空闲超时（2秒）检测完成
- **会话恢复**：卡住的shell在重复的提示检测失败后自动重置
## 文档
| 文档 | 主题 |
| --- | --- |
| [API-DOCS.md](./API-DOCS.md) | 完整API参考 — 类型、SSHService方法、MCP工具、错误模型 |
| [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) 进行重大重构。
