内容
# SSH MCP 服务器
一个MCP（模型上下文协议）服务器，通过工具暴露SSH操作，允许AI代理运行命令、执行脚本、传输文件，并在远程虚拟机上通过SSH管理长时间运行的后台作业。
连接到任何可通过SSH访问的机器。支持基于密钥的身份验证、密码身份验证、AWS Secrets Manager和托管在S3上的密钥。
## 工具
### Shell
| 工具 | 参数 | 描述 |
|---|---|---|
| `ssh_run_command` | `command`, `sudo=false` | 在远程虚拟机上运行shell命令。返回 `stdout`, `stderr`, `exit_code`。 |
| `ssh_run_command_with_timeout` | `command`, `timeout`, `sudo=false` | 与上述相同，但具有自定义超时（秒）。 |
| `ssh_run_script` | `content`, `interpreter=bash`, `timeout=30`, `sudo=false`, `working_dir=/tmp` | 通过SFTP将脚本写入远程虚拟机并执行。支持任何解释器（`bash`, `python3`, `sh`等）。 |
### 后台作业
| 工具 | 参数 | 描述 |
|---|---|---|
| `ssh_run_background` | `command`, `sudo=false` | 使用 `nohup` 在后台运行命令。返回 `job_id` 和 `pid`。 |
| `ssh_check_job` | `job_id` | 检查后台作业的状态。返回 `status`（running/done/failed），`output`，`exit_code` 和 `process_info`（PID，CPU%，MEM%，已用时间）。 |
后台作业将输出写入远程虚拟机上的 `/tmp/_mcp_job_<id>.*`，并且在SSH重新连接后仍然存在。使用 `job_id`（而不是 `pid`）和 `ssh_check_job`。
### 文件传输（SCP）
| 工具 | 参数 | 描述 |
|---|---|---|
| `ssh_scp_upload` | `local_filename`, `remote_path` | 将文件从本地工作空间（`FILE_PATH`）推送到远程虚拟机上的绝对路径。 |
| `ssh_scp_download` | `remote_path`, `local_filename` | 将文件从远程虚拟机上的绝对路径拉取到本地工作空间（`FILE_PATH`）。 |
### 工作空间（本地 `FILE_PATH`）
| 工具 | 参数 | 描述 |
|---|---|---|
| `workspace_list` | — | 列出本地工作空间中的所有文件。 |
| `workspace_read` | `filename` | 从本地工作空间读取文件。限制在 `FILE_PATH` — 拒绝路径遍历。 |
| `workspace_write` | `filename`, `content` | 在本地工作空间中写入或覆盖文件。限制在 `FILE_PATH` — 拒绝路径遍历。 |
工作空间是SCP传输的暂存区。在Docker中，将主机目录挂载到它。在AgentCore中，附加S3 Files或EFS访问点。
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `HOST_IP` | 是 | — | 远程虚拟机的IP地址或主机名 |
| `USERNAME` | 是 | — | 远程虚拟机上的SSH用户 |
| `SECRET_NAME` | 四选一 | — | AWS Secrets Manager密钥名称（包含 `SSH_KEY` 或 `PASSWORD` 的JSON） |
| `SECRET_REGION` | 否 | `us-east-1` | Secrets Manager的区域 |
| `S3_BUCKET` + `S3_KEY` | 四选一 | — | 指向PEM密钥文件的S3对象路径 |
| `AWS_REGION` | 否 | `us-east-1` | S3的区域 |
| `SSH_KEY` | 四选一 | — | PEM私钥字符串（在 `.env` 文件中使用 `\n` 表示换行） |
| `PASSWORD` | 四选一 | — | SSH密码 |
| `PORT` | 否 | `8000` | 此服务器监听的HTTP端口 |
| `SSH_PORT` | 否 | `22` | 远程虚拟机上的SSH端口 |
| `FILE_PATH` | 否 | `/transfers` | SCP和工作空间工具的本地暂存目录 |
| `IDLE_TIMEOUT` | 否 | `60` | 空闲SSH连接关闭前的秒数 |
**身份验证优先级：** `SECRET_NAME` → `S3_BUCKET`+`S3_KEY` → `SSH_KEY` → `PASSWORD`
## MCP 端点
```
http://localhost:8000/mcp
```
健康检查：
```
http://localhost:8000/health
```
## 部署
- [本地部署](./docs/local-deploy.md) — Docker和本地Python设置
- [AgentCore部署](./docs/agentcore-deploy.md) — 带有VPC、S3 Files和网关的AWS AgentCore运行时部署
