内容
# Codex SSH Terminal MCP
**基于代理的 SSH 控制平面，具备本地 Web Terminal、人工介入的密钥输入、基于密钥链的配置文件以及用户确认的上传功能，适用于 Codex、Claude Code 和 MCP 兼容的编码代理。**
[简体中文](README.zh-CN.md) | [Security](SECURITY.md) | [Usage Workflow](docs/usage-workflow.en.md)
`codex-ssh-terminal-mcp` 允许 AI 编码代理通过本地用户控制的桥梁操作 SSH 会话。它适用于您通常需要打开 Xshell、SecureCRT、iTerm 或其他 SSH 客户端，手动运行命令，复制终端输出回代理，然后重复的工作流。
已经存在其他面向 SSH 的 MCP 服务器。该项目专注于不同的操作模式：共享的本地 Web Terminal，代理可以观察和操作，而用户在本地控制界面中保留凭证、多因素身份验证、堡垒交互和文件传输审批。
<sub>本地 Web Terminal 和配置文件页面，仅包含示例连接占位符。</sub>
<sub>演示截图，包含已编辑/示例服务器数据。</sub>
该项目不是传统的 SSH 客户端克隆。它将 SSH 终端转变为代理可观察和用户控制的执行通道：
- 代理可以增量读取终端输出。
- 代理可以通过 MCP 工具发送命令。
- 用户在本地浏览器页面中保留密码、多因素身份验证代码和上传审批。
- 远程服务器仍然使用标准 SSH、堡垒、sudo、ACL 和审计边界。
## ✨ 它是什么
该项目位于三个层之间：
```text
Codex / Claude Code / MCP 客户端
|
| MCP 工具
v
本地 MCP 服务器 + 本地桥梁 + Web Terminal
|
| SSH / SCP / rsync
v
服务器 / 堡垒 / 跳转服务器 / ProxyJump 目标
```
代理不需要知道您的 SSH 密码。用户不需要重复将终端输出复制到聊天中。服务器不需要任何自定义代理端守护进程。
结果是适用于代理辅助服务器操作的本地 SSH 控制平面，优化了安全性、共享可见性和用户确认与命令执行同样重要的工作流。
## 🎯 为什么存在
传统的 SSH 工具是为人类操作终端而构建的。代理辅助操作需要不同的接口：
- **可观察性**：代理需要结构化访问终端输出。
- **交互性**：代理需要发送命令并响应远程提示。
- **边界性**：秘密和高影响力的操作应保留在用户控制下。
- **增量性**：长日志和安装进度不应淹没代理上下文。
- **兼容性**：远程端应保持纯 SSH、堡垒或 ProxyJump。
该项目旨在减少以下操作的摩擦：
- 服务器环境检查
- 日志检查
- Docker / Redis / PostgreSQL / Nginx 诊断
- 安装和安装后验证
- 堡垒或跳转服务器菜单交互
- 用户确认的文件上传
- 替换“在 Xshell 中运行，将输出粘贴到代理”的循环
## 🧠 能力模型
### 观察
代理可以读取具有光标和尾部限制的增量终端输出。这避免了在每一步重新加载完整的终端历史记录，并防止嘈杂的进度输出占用整个上下文窗口。
### 操作
代理可以通过 MCP 工具向共享的 SSH 会话发送命令。这适用于普通 shell、交互式提示和菜单样式的堡垒，只要终端交互在共享会话中可见即可。
### 确认
文件上传等高影响力流程是人工介入的。代理可以请求上传，但用户必须在本地网页中确认，然后再开始传输。
### 持久
用户可以保存连接配置文件。代理可以稍后列出已编辑的配置文件元数据，并在无需用户将凭证粘贴到聊天中的情况下连接到选定的配置文件。
### 约束
桥梁是本地优先的、基于令牌保护的、源检查的，旨在将敏感的连接详细信息排除在代理上下文之外。
## 🔐 安全设计
该项目围绕一个简单的规则构建：
> 代理可以操作授权的 SSH 会话，但不应需要拥有您的秘密。
已实施的安全功能包括：
- **凭证隔离**
- SSH 密码、多因素身份验证代码、私钥内容和云访问秘密应仅在本地网页中输入。
- 后端避免请求体日志记录。
- 机密不应粘贴到 Codex、Claude Code 或任何代理聊天中。
- **系统密钥链支持的配置文件**
- macOS：钥匙串。
- Linux / WSL：通过 `secret-tool` 使用秘密服务。
- 本地配置文件存储配置文件名称、描述、已编辑提示和密钥链引用。
- 新创建的配置文件不存储完整的 host、用户、ProxyJump 或原始 SSH 命令值在普通项目文件中。
- **代理最小知识**
- MCP 配置文件列表返回已编辑的元数据。
- 代理无需查看密码、验证码、私钥或完整的连接详细信息。
- 密钥链支持的配置文件不会以可编辑的纯文本形式反射回页面。
- **本地 API 加固**
- 桥梁默认绑定到 `127.0.0.1`。
- 拒绝非本地绑定地址。
- `/api/*` 和 `/events` 需要随机本地 API 令牌。
- MCP 调用使用 `Authorization: Bearer ...`。
- 浏览器访问使用同源 `HttpOnly` cookie。
- **浏览器源保护**
- 请求必须使用本地 `Host`。
- 浏览器 cookie 写请求必须来自同源 `Origin` 或 `Referer`。
- 这降低了恶意本地网页通过 CSRF 样式请求驱动桥梁的风险。
- **人工介入的文件上传**
- 代理可以创建上传请求。
- 用户必须在网页中批准。
- 上传完成报告远程路径、远程大小验证和可选的 SHA-256 验证。
- 上传传输通过 `scp` 或 `rsync` 进行，而不是通过共享的终端历史记录。
- **有限的本地状态**
- 终端历史记录增量读取。
- 嘈杂的进度输出被压缩供代理读取。
- 桥梁日志轮换。
- 上传任务过期并压缩其日志。
- **无权限绕过**
- 该项目不绕过 SSH、堡垒策略、跳转服务器权限、sudo 规则、ACL 或审计系统。
- 远程权限正是您连接的帐户的权限。
参见 [SECURITY.md](SECURITY.md) 以获取详细的安全边界。
## ⚠️ 权限风险声明
该项目基于适用于 Codex 和 Claude Code 等代理的 MCP 扩展功能。使用它意味着您允许代理参与您已经有权访问的 SSH 会话中的操作。
由广泛的服务器权限、不安全的生产帐户、错误的代理指令、第三方模型行为或用户批准的破坏性命令引起的风险不在该项目的责任范围内。该项目提供了一个受控的本地通道、凭证隔离、令牌保护、源检查和用户确认点；它不保证代理生成的每个命令都是安全的。
推荐的做法：
- 在可能的情况下使用低权限帐户
- 将生产 root 访问权限排除在默认配置文件之外
- 在执行前审查高影响力的命令
- 保持堡垒和服务器端审计启用
- 完成任务后停止桥梁
## 🧩 支持的连接形状
| 连接形状 | 共享终端 | 文件上传 | 备注 |
| --- | --- | --- | --- |
| 直接 SSH | 支持 | 支持 | 标准主机 / 端口 / 用户配置文件。 |
| SSH 堡垒主机 | 支持 | 支持到堡垒主机本身 | 第二跳上传需要可寻址路由。 |
| ProxyJump | 支持 | 支持 | 使用带有 `ProxyJump` 的结构化配置文件。 |
| 基于菜单的堡垒 / 跳转服务器 | 支持 | 不直接适用于第二跳资产 | 为需要上传的资产创建直接或 ProxyJump 配置文件。 |
平台边界：
| 平台 | 状态 | 备注 |
| --- | --- | --- |
| macOS | 支持 | 使用 POSIX PTY 和系统 OpenSSH。 |
| Linux | 支持 | 需要 `ssh` / `scp`；密钥链配置文件需要秘密服务。 |
| 通过 WSL 的 Windows | 支持 | 在 WSL 中运行 MCP。 |
| 原生 Windows | 暂不支持 | 需要 ConPTY / pywinpty 后端。 |
## 🚀 快速入门
从源代码安装：
```bash
git clone <your-repo-url>
cd codex-ssh-terminal-mcp
python3 -m pip install -e .
```
在您的 MCP 客户端中注册 MCP 服务器。对于 Codex 样式的配置：
```toml
[mcp_servers.codex-ssh-terminal-mcp]
command = "codex-ssh-terminal-mcp"
args = []
```
如果您不安装控制台脚本，请直接使用源代码脚本：
```toml
[mcp_servers.codex-ssh-terminal-mcp]
command = "python3"
args = ["/path/to/codex-ssh-terminal-mcp/mcp_server.py"]
```
然后要求您的代理启动配置页面：
```text
使用 codex-ssh-terminal-mcp 启动配置页面。
```
打开返回的本地 URL，创建连接配置文件，并仅在本地网页中输入密码或多因素身份验证提示。
保存配置文件后，要求代理连接：
```text
连接到已保存的堡垒配置文件。
```
## 🛠️ MCP 工具概述
MCP 服务器为代理驱动的 SSH 工作提供了工具：
- `start_config_server`: 启动本地配置页面而不打开 SSH。
- `list_profiles`: 列出已保存的已编辑连接配置文件。
- `start_bridge`: 从配置文件启动本地 Web 终端和 SSH 桥梁。
- `bridge_status`: 检查桥梁和 SSH 会话状态。
- `send_command`: 向共享的 SSH 终端发送命令。
- `snapshot`: 读取增量终端输出。
- `reset_cursor`: 重置代理端的增量读取光标。
- `clear_history`: 清除内存终端历史记录。
- `control`: 发送终端控制命令，如 `ctrl-c`、`ctrl-d` 或 `enter`。
- `request_upload`: 请求用户确认的文件上传。
- `list_uploads`: 列出上传请求和传输状态。
- `upload_status`: 检查上传请求。
- `cancel_upload`: 取消上传。
- `stop_bridge`: 停止 SSH 桥梁。
- `runtime_config_status` / `set_runtime_config`: 控制桥梁 Python 运行时如何启动。
凭证和多因素身份验证代码不应通过这些工具传递。
## 💬 示例代理提示
对于 Codex：
```text
使用 codex-ssh-terminal-mcp 启动配置页面。
```
```text
连接到已保存的堡垒配置文件。
```
```text
检查此服务器上正在运行哪些服务。
```
```text
检查 PostgreSQL 是否已安装以及哪些端口正在监听。
```
```text
请求将此本地文件上传到 /tmp/app.tar.gz。我将在页面中确认。
```
对于 Claude Code 或另一个 MCP 兼容客户端，请将此项目配置为 MCP 服务器，然后使用相同的流程：启动页面、保存配置文件、连接配置文件、读取输出、发送命令、确认上传。
## 🖥️ 它与 Xshell / SecureCRT 的关系
Xshell 和 SecureCRT 是优秀的人类首选 SSH 客户端。该项目服务于不同的工作流程。
它专注于：
- MCP 集成
- 代理可读的终端输出
- 增量观察
- 本地秘密隔离
- 用户确认的上传
- 代理辅助的诊断和操作循环
它可以取代部分手动的“打开 Xshell，运行命令，将输出复制到代理”的工作流程。它不打算取代专业 SSH 客户端的每个功能。
## 🧭 典型工作流程
1. 通过 MCP 启动本地配置页面。
2. 在页面中创建直接 SSH、堡垒、ProxyJump 或基于命令的配置文件。
3. 在系统密钥链中存储真实的连接详细信息。
4. 请求代理列出可用的配置文件。
5. 请求代理启动一个配置文件的桥梁。
6. 在本地页面中输入密码、多因素身份验证或堡垒菜单选择。
7. 让代理读取增量输出并发送命令。
8. 在页面中确认上传或高影响交互。
9. 任务完成后停止桥梁。
## 🧱 限制
- 该项目不提供权限提升。
- 该项目不绕过堡垒或服务器端审计。
- 该项目不保证代理生成的命令是正确的。
- 原生 Windows 暂不支持；使用 WSL。
- 基于菜单的堡垒依赖于稳定的终端提示和菜单输出。
- 自动上传到第二跳菜单选择的资产需要单独的可寻址 SSH 路由。
- 高风险生产操作仍应由人审查。
## 🤝 社区 / 贡献者呼吁
该项目由个人开发者从实际的代理辅助服务器操作需求开始。
核心路径已经实现：MCP 集成、本地 Web Terminal、SSH 桥梁、配置文件管理、系统密钥链存储、本地 API 令牌保护、Host / Origin / Referer 检查、用户确认的上传、增量终端读取、上传验证和有限的本地日志。
话虽如此，一名开发者时间有限，测试环境和安全审查能力也有限。 贡献非常欢迎，尤其是在：
- 更多 MCP 客户端兼容性
- 原生 Windows 终端后端
- Linux 秘密服务兼容性测试
- 额外的堡垒和跳转服务器场景
- 更强的安全审查
- 文件传输强化
- UI / UX 改进
- 文档和安装体验
- 现实世界的兼容性报告
目标不是构建一个封闭的工具。目标是探索代理如何安全地参与服务器操作。
## 📄 许可证
该项目在 [Apache License 2.0](LICENSE) 下许可。
对于安全敏感的问题，请避免在公共问题中发布秘密。先旋转暴露的凭证，然后用编辑后的详细信息报告。
