Skip to main content
Glama
Rex SSH MCP

Rex SSH MCP

by lunix1024

Rex SSH MCP

English | 简体中文

CI License: MIT

一个通过 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 config

MCP 客户端配置:

{
  "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 config

Windows 下也可以直接双击项目根目录的 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 工具

工具

作用

ssh_list_servers

查询服务器别名、主机、端口、登录用户、指纹配置状态和连接状态

ssh_exec

执行非交互 shell 命令

ssh_read_file

读取 UTF-8 文本文件

ssh_write_file

原子写入 UTF-8 文本并可备份

ssh_list_dir

列出远程目录

ssh_stat

查看远程路径元数据

ssh_tail_file

读取日志末尾行

ssh_upload_file

上传本机文件

ssh_download_file

下载远程文件

ssh_reconnect

重载并立即验证指定服务器配置

除了 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 tools
ssh_download_fileA
Destructive

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_execA
Destructive

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_dirA
Read-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_serversA
Read-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_fileA
Read-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_reconnectA
Read-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_statA
Read-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_fileA
Read-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_fileA
Destructive

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_fileA
Destructive

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

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Manages multiple SSH servers through a local workspace with MCP tools, executing commands and transferring files securely with credential isolation.
      9
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT