Rex SSH MCP
You can manage multiple preconfigured remote Linux servers over SSH/SFTP through MCP using exact server aliases, with credentials kept private server-side.
Discover configured servers and filter by alias, host/IP, or username.
Run non-interactive shell commands with timeouts and blocking of common destructive commands.
Read, write, and inspect remote files/directories, including atomic writes with backups and symlink protections.
Tail remote log files and list directory entries.
Upload local files to remote servers and download remote files to local paths.
Reload and validate a selected server’s configuration with reconnect.
Rely on server-side credential storage: tools never accept or return passwords.
Provides tools for managing remote Linux servers over SSH, including executing commands, reading and writing files, listing directories, checking metadata, tailing logs, and uploading/downloading files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Rex SSH MCP check disk space on server 148"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Rex SSH MCP
English | 简体中文
一个通过 MCP 操作多台远程 Linux 服务器的本地 stdio 服务。每台服务器使用别名选择,密码由 Windows DPAPI 按当前用户加密保存;MCP 工具和聊天内容不接收密码。
环境要求
Windows 10/11 或 Windows Server
Node.js 22 或更高版本
允许密码认证和 SFTP 的远程 SSH 服务
Related MCP server: MSAW
通过 npx 使用
本仓库已支持 npm 打包;以下包名命令需要维护者先将对应版本发布到 npm。
首次使用,在交互式终端中配置服务器:
npx -y rex-ssh-mcp configMCP 客户端配置:
{
"command": "npx",
"args": ["-y", "rex-ssh-mcp"]
}如果 Windows 客户端无法直接启动 npx,可将 command 改为 cmd,args 改为 ["/c", "npx", "-y", "rex-ssh-mcp"]。需要固定版本时,将包名改为 rex-ssh-mcp@2.0.0。
无需克隆仓库或手动编译。npx 会下载并缓存发布包,然后启动 stdio 服务;也可用 npm install -g rex-ssh-mcp 全局安装,再运行 rex-ssh-mcp config 和 rex-ssh-mcp。
npm 命令默认将配置保存到 $HOME/.rex-ssh-mcp/servers.json,日志保存到同目录的 logs/rex-ssh-mcp.log,升级或清理 npx 缓存不会删除这些数据。npx -y rex-ssh-mcp --help 可查看实际路径,--version 可查看版本。
可设置环境变量 REX_SSH_MCP_HOME 指定数据目录;配置工具与 MCP 客户端需要使用相同的值。例如,继续使用已有仓库配置:
$env:REX_SSH_MCP_HOME = 'D:/path/to/rex-ssh-mcp'
npx -y rex-ssh-mcp config在 MCP 客户端配置中同步添加 "env": { "REX_SSH_MCP_HOME": "D:/path/to/rex-ssh-mcp" }。也可以在相同 Windows 用户下将原有 servers.json 复制到默认用户目录;跨机器或更换用户时需要重新录入密码。
从源码使用
克隆、安装并编译:
git clone https://github.com/lunix1024/rex-ssh-mcp.git
Set-Location rex-ssh-mcp
npm install
npm run build配置服务器
运行中文交互式配置界面:
npm run configWindows 下也可以直接双击项目根目录的 config-servers.bat。脚本会自动切换到项目目录、检查 Node.js/npm/依赖,并打开同一个配置界面;启动失败时窗口会保留错误信息。
TUI 支持查看、新增、编辑、修改密码、测试连接和删除服务器。密码输入会被遮罩,随后使用 Windows DPAPI CurrentUser 加密。从源码运行时,配置默认保存在项目根目录的 servers.json;npm 命令使用前文所述用户目录,设置 REX_SSH_MCP_HOME 可覆盖两种入口的目录。配置结构如下:
菜单中的每个选项都有编号:输入编号会定位并高亮对应项,按 Enter 确认,也可以使用方向键。所有子页面按 Esc 返回上一层,主菜单按 Esc 退出。编辑服务器信息时会先展示各字段当前值,可只选择需要修改的字段;多项修改保存在内存草稿中,选择“保存全部修改”后才会一次性写入配置。
新增服务器只需填写别名、主机名/IP、端口、登录用户和一次密码;修改密码也只需输入一次。配置界面不再提供主机指纹输入项,已有配置中的 hostFingerprint 仍会参与连接校验;如需配置指纹,可手动编辑该可选字段。
{
"version": 1,
"servers": [
{
"alias": "生产-148",
"host": "192.0.2.148",
"port": 22,
"username": "operator",
"encryptedPassword": "dpapi:v1:<由 TUI 生成的密文>",
"hostFingerprint": "SHA256:可选的OpenSSH主机公钥指纹"
}
]
}不要手工填写或传递明文密码。servers.json 已加入 .gitignore;它只包含 DPAPI 密文,但仍应限制不受信任用户读取。DPAPI 密文与加密时的 Windows 用户上下文绑定:更换用户、重装系统或迁移机器后,需要重新录入密码。相同 Windows 用户下运行的程序有能力请求 DPAPI 解密,因此这是静态存储保护,不是对已被攻陷账户的隔离。
启动 MCP Server
npm start开发模式:
npm run dev这是 stdio MCP 服务,启动后会等待客户端通过 stdin 发送协议消息,不会打开浏览器,也不会在启动时连接 SSH。日志写入 logs/rex-ssh-mcp.log,并同步写到 stderr;stdout 仅用于 MCP 协议。
Codex 的 MCP 配置可指向:
{
"command": "node",
"args": ["D:/path/to/rex-ssh-mcp/dist/index.js"]
}请把示例路径替换为本机仓库的绝对路径。首次使用前先运行 npm run build 和 npm run config。
服务器选择规则
所有操作工具都要求 server 参数,并且只能使用配置中的准确别名。用户可以自然地说:
通过 MCP 检查 148 服务器的磁盘空间
模型应先调用 ssh_list_servers,用 148 过滤别名、主机/IP 和用户名。如果只有一个结果,就在后续每次工具调用中自动携带该规范别名;没有结果或存在多个结果时必须要求用户确认,不能猜测。服务端没有全局“当前服务器”,因此并发任务不会因切换目标而串到另一台机器。
MCP 工具
工具 | 作用 |
| 查询服务器别名、主机、端口、登录用户、指纹配置状态和连接状态 |
| 执行非交互 shell 命令 |
| 读取 UTF-8 文本文件 |
| 原子写入 UTF-8 文本并可备份 |
| 列出远程目录 |
| 查看远程路径元数据 |
| 读取日志末尾行 |
| 上传本机文件 |
| 下载远程文件 |
| 重载并立即验证指定服务器配置 |
除了 ssh_list_servers 外,每个工具都必须传入准确的 server 别名。配置文件变化会在下一次调用时自动生效:新请求使用新的连接代次,已经在执行的请求结束后旧连接才关闭。不同服务器分别懒连接并独立复用。
安全行为
密码不会出现在 MCP 参数、服务器列表、正常结果或错误结果中。
只有实际连接某台服务器时才解密该服务器密码;解密后立即加入全局日志和返回值脱敏集合。
重连或修改密码后,新旧密码都会继续脱敏,保护仍在结束的旧请求。
DPAPI 调用使用固定 PowerShell 脚本,敏感数据只经过 stdin/stdout 管道,不进入命令行或环境变量。
可配置 OpenSSH SHA256 主机公钥指纹;正式环境建议启用。
常见的整机删除、格式化磁盘和关机命令会被阻止,但这不是完整 shell 沙箱。应使用权限受限的专用 SSH 账号。
命令、路径和非 SSH 密码的业务密钥可能进入运行日志,日志目录应只允许受信任的本机用户读取。
缺少 servers.json 或服务器列表为空时,MCP 仍能启动,ssh_list_servers 返回空列表;其他工具返回 server_not_configured。损坏配置、未知别名和 DPAPI 解密失败分别返回固定错误,不传播第三方错误文本。
测试
npm test测试使用本机环回 SSH/SFTP 服务,不连接真实服务器,覆盖配置校验、多服务器路由、连接复用与重连、热更新、危险命令、传输、输出限额以及多密码脱敏。DPAPI 往返测试仅在 Windows 运行。
npm 打包与发布
npm test
npm pack --dry-run
npm pack打包前会自动编译 TypeScript。发布包使用文件白名单,仅包含编译后的 JavaScript、包元数据、README、许可证和安全说明,不包含 servers.json、日志、测试或开发依赖。
发布前可使用生成的本地包验证入口(文件名随版本变化):
npx -y --package ./rex-ssh-mcp-2.0.0.tgz rex-ssh-mcp --help确认包名属于自己的 npm 账号、版本尚未发布后,由维护者运行 npm login 和 npm publish。如包名不可用,应先调整 package.json 中的名称并同步使用文档中的命令。
参与贡献
欢迎提交 Issue 和 Pull Request。开始前请阅读 CONTRIBUTING.md,安全问题请按照 SECURITY.md 私下报告,不要在公开 Issue 中披露凭据或漏洞细节。
许可证
本项目基于 MIT License 开源。
Available Tools
10 toolsssh_download_fileADestructive
Download a remote file from the selected server through SFTP to an absolute local path. Existing local files are not overwritten by default. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: server (required), localPath (required), remotePath (required), timeout, +1 more.
ssh_execADestructive
Execute a shell command on the selected remote Linux server. Timeout is in seconds (default 30, maximum 300); stdout and stderr are capped at 1 MiB each. Common destructive commands are blocked. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: server (required), command (required), timeout.
ssh_list_dirARead-only
List a remote directory through SFTP on the selected server, returning at most 10000 entries. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: path (required), server (required).
ssh_list_serversARead-onlyIdempotent
List configured SSH servers, optionally filtering by alias, host/IP fragment, or username. Returns only non-secret metadata and connection status. A unique result provides the exact alias required by all operation tools. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: query.
ssh_read_fileARead-only
Read a remote UTF-8 regular file through SFTP on the selected server, default 1 MiB, maximum 5 MiB. Oversized text is truncated and binary content is rejected. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: path (required), server (required), maxBytes.
ssh_reconnectARead-onlyIdempotent
Reload and immediately validate the selected server configuration. Other server connections are not affected. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: server (required).
ssh_statARead-only
Inspect a remote path through SFTP lstat on the selected server. The final symlink is not followed. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: path (required), server (required).
ssh_tail_fileARead-only
Read the last lines of a remote log file on the selected server. Output is capped and the timeout is 30 seconds. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: path (required), server (required), lines.
ssh_upload_fileADestructive
Upload a local file to the selected remote server through SFTP. The local path must be absolute; replacement is atomic and backed up by default. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: server (required), localPath (required), remotePath (required), timeout, +1 more.
ssh_write_fileADestructive
Write UTF-8 text through SFTP on the selected server using a temporary file and atomic rename. Existing files are backed up by default. Replacing symlinks is refused. SSH credentials are private server-side configuration. Never ask the user for a password. Use ssh_list_servers when the user has not supplied an exact configured alias.
Inputs: path (required), server (required), content (required), createBackup.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct operation: server listing/reconnect, command execution, file metadata, content reading, writing, directory listing, tailing, upload, and download. No two tools overlap in purpose, and edge cases like stat vs read_file vs tail_file are clearly differentiated.
All tools follow the ssh_ prefix with a consistent verb_noun pattern (list_servers, read_file, write_file, list_dir, upload_file, download_file, tail_file). The uniform style makes the tool surface predictable and easy to navigate.
Ten tools is well-scoped for an SSH/SFTP server management server. Each tool earns its place, covering connection management, remote execution, and file operations without redundant or excessive entries.
The core SSH/SFTP workflow is well covered: exec, read, write, list, stat, tail, upload, download. A notable gap is the lack of a delete/remove operation for remote files or directories, and no rename/mkdir, but most common administrative tasks can be completed with the existing surface.
Maintenance
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server for administering Linux/Unix hosts via SSH and Windows hosts via WinRM/PowerShell Remoting, supporting persistent inventory, sessions, jobs, and command groups.30MIT
- AlicenseAqualityBmaintenanceManages multiple SSH servers through a local workspace with MCP tools, executing commands and transferring files securely with credential isolation.91MIT
- AlicenseAqualityCmaintenanceEnables remote command execution and SFTP file upload or download from any MCP client without a local SSH client, SCP, or PuTTY installed. Supports password or private key authentication with SHA256 host fingerprint verification, timeouts, output limits, and multiple configured server instances.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables managing multiple Linux SSH servers from MCP clients, with structured filesystem operations, shell commands, durable long-running jobs, process listing, and CPU/RAM/disk/GPU status.MIT