内容
# 远程 SSH MCP 服务器
用于通过 SSH 将 MCP 客户端连接到远程 Linux 或 Unix 主机。
它提供远程 shell 命令、目录列表、文本和二进制文件访问、SSH 端口转发和 VS Code Remote-SSH URI 生成。服务器在本地运行，并重用 OpenSSH 安装、配置、密钥、代理和 `ProxyJump` 设置，这些设置已经在用户的机器上可用。
## 网络模型
此 MCP 服务器在远程服务器无法访问互联网时非常有用，或者当您不希望远程服务器使用自己的出站网络连接时。
MCP 客户端和 `remote-ssh-mcp` 进程在本地计算机上运行。请求通过 SSH 从本地计算机发送到远程服务器，因此远程服务器不需要互联网连接来进行 MCP 通信。唯一的要求是本地计算机可以访问服务器的 SSH 地址和端口。
这不会为远程命令提供互联网访问。诸如 `curl`、`wget`、`git clone`、`npm install` 或 `pip install` 等命令仍在远程服务器上运行，需要来自该服务器的网络访问。要通过本地计算机获取文件或数据，请先在本地下载，然后使用 `remote_ssh_write_file_base64`，或在适当的情况下使用 SSH 端口转发。
## 快速设置
克隆仓库，安装依赖项，然后运行交互式设置向导：
```powershell
git clone https://github.com/bbt567/remote-ssh-mcp.git
cd remote-ssh-mcp
npm ci
npm run setup
```
向导：
1. 列出已保存的服务器配置文件或创建新的配置文件。
2. 请求服务器 IP/主机名、SSH 用户、端口和私钥路径。
3. 检测现有的 SSH 密钥或生成 Ed25519 密钥。
4. 测试公钥身份验证。
5. 提供在服务器上安装公钥的选项。OpenSSH 可能需要服务器密码；向导不会读取或存储密码。
6. 在 `~/.remote-ssh-mcp/profiles.json` 中保存配置文件。
7. 在 Codex Desktop/CLI 和/或 Claude Code 中安装特定于配置文件的 MCP 条目。
8. 生成特定于配置文件的 JSON 配置作为可移植备份。
设置完成后，请重启选定的客户端。Codex Desktop 和 Codex CLI 共享相同的 `~/.codex/config.toml`，因此安装到任一 Codex 界面都会启用两者。
中文说明可在 [docs/SETUP.zh-CN.md](docs/SETUP.zh-CN.md) 中找到。
## 多个服务器
再次运行 `npm run setup` 以添加另一个服务器。保存的配置文件将在连接问题之前显示，因此可以选择现有的服务器而无需重新输入其地址、用户、端口或密钥路径。
`default` 配置文件被安装为 `remote-ssh`。其他配置文件使用不同的 MCP 服务器名称：
```text
default -> remote-ssh
production -> remote-ssh-production
staging -> remote-ssh-staging
```
列出已保存的配置文件：
```powershell
npm run profiles
```
删除本地配置文件：
```powershell
npm run profiles -- remove staging
```
删除配置文件不会删除其 Codex 或 Claude Code MCP 条目。
## 要求
- Node.js 20 或更高版本
- OpenSSH 客户端可用作 `ssh`
- 为目标主机配置 SSH 公钥身份验证
- 支持 stdio 服务器的本地 MCP 客户端
在配置 MCP 客户端之前，请验证 SSH：
```powershell
ssh 192.0.2.10 "hostname && whoami && pwd"
```
如果您的 SSH 设置需要用户名或非默认端口，请使用以下环境变量或在 `~/.ssh/config` 中配置它们。
## 从源代码安装
```powershell
git clone https://github.com/bbt567/remote-ssh-mcp.git
cd remote-ssh-mcp
npm ci
npm run setup
```
仓库不存储 SSH 密码、私钥或令牌。
## MCP 客户端配置
设置向导使用配置文件名称和配置文件安装客户端：
```json
{
"mcpServers": {
"remote-ssh": {
"command": "node",
"args": [
"C:\\path\\to\\remote-ssh-mcp\\dist\\index.js"
],
"env": {
"REMOTE_SSH_PROFILE": "production",
"REMOTE_SSH_PROFILES_FILE": "C:\\Users\\your-name\\.remote-ssh-mcp\\profiles.json"
}
}
}
}
```
直接 `SSH_HOST`、`SSH_USER`、`SSH_PORT` 和 `SSH_IDENTITY_FILE` 配置为了兼容性而仍然受支持。显式环境变量覆盖配置文件值。
`REMOTE_SSH_*` 变量作为显式命名空间等价物得到支持。当两者都存在时，`REMOTE_SSH_*` 优先。
## 工具
- `remote_ssh_check`：检查 SSH 连接并返回远程身份详细信息。
- `remote_ssh_local_diagnostics`：检查本地 OpenSSH 环境和连接。
- `remote_ssh_exec`：运行 shell 命令，可选的工作目录和环境。
- `remote_ssh_list_dir`：使用 `ls -la` 列出远程目录。
- `remote_ssh_read_text`：读取带有字节限制的远程文本文件。
- `remote_ssh_read_file_base64`：读取小的远程二进制文件为 base64。
- `remote_ssh_write_text`：将 UTF-8 文本写入远程文件。
- `remote_ssh_write_file_base64`：解码 base64 并写入远程文件。
- `remote_ssh_start_port_forward`：启动本地 SSH `-L` 端口转发。
- `remote_ssh_list_port_forwards`：列出此进程创建的端口转发。
- `remote_ssh_stop_port_forward`：停止此进程创建的端口转发。
- `remote_ssh_uri`：生成 VS Code Remote-SSH URI 和 CLI 命令。
每个远程工具都接受一个可选的 `host` 字段，该字段覆盖为该调用配置的目标。命令和文件写入工具故意强大；请在 MCP 客户端中批准它们之前审查工具调用。
## 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `REMOTE_SSH_PROFILE` | 无 | 要加载的已保存配置文件 |
| `REMOTE_SSH_PROFILES_FILE` | `~/.remote-ssh-mcp/profiles.json` | 本地配置文件 |
| `SSH_HOST` | 无 | 默认主机名、别名或 IP 地址 |
| `SSH_USER` | OpenSSH 默认值 | 添加到 `SSH_HOST` 的用户名（如果没有 `@`） |
| `SSH_PORT` | OpenSSH 默认值 | SSH TCP 端口 |
| `SSH_BIN` | 平台 OpenSSH | SSH 可执行文件路径 |
| `SSH_IDENTITY_FILE` | OpenSSH 默认值 | 传递给 OpenSSH 的私钥路径 |
| `REMOTE_SSH_HOST` | 无 | `SSH_HOST` 的命名空间等价物 |
| `REMOTE_SSH_USER` | OpenSSH 默认值 | `SSH_USER` 的命名空间等价物 |
| `REMOTE_SSH_PORT` | OpenSSH 默认值 | `SSH_PORT` 的命名空间等价物 |
| `REMOTE_SSH_BIN` | 平台 OpenSSH | `SSH_BIN` 的命名空间等价物 |
| `REMOTE_SSH_IDENTITY_FILE` | OpenSSH 默认值 | `SSH_IDENTITY_FILE` 的命名空间等价物 |
| `REMOTE_SSH_TIMEOUT_MS` | `60000` | 默认命令超时 |
| `REMOTE_SSH_MAX_OUTPUT_BYTES` | `1048576` | 默认捕获的每个输出流的字节数 |
## 开发
```powershell
npm run typecheck
npm run build
npm run dev
npm run setup
npm run profiles
```
MCP 服务器使用 stdio。日志写入 stderr，因此 MCP 协议流保持干净。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
