Skip to main content
Glama
remote-ssh-mcp
by RuiFG

Remote SSH MCP

在 Codex CLI 和 Claude Code 中管理 SSH 主机、运行远端命令、传输文件。Windows 和 WSL 客户端可以共用 WSL 中安装的一份服务、同一份主机列表与已保存凭据。每个会话拥有独立的 SSH 连接和远端工作目录。

安装 v1.0.0

在 WSL 或 Linux 中运行以下命令。需要 Node.js 22.19.0 或更高版本和 npm。远端机器需要 SSH 服务,文件传输还需要 SFTP。

npm install --global --prefix "$HOME/.local" https://github.com/RuiFG/remote-ssh-mcp/releases/download/v1.0.0/remote-ssh-mcp-1.0.0.tgz
"$HOME/.local/bin/remote-ssh-mcp" --version

此安装包包含已编译的 MCP 服务、操作指引和许可证。版本命令应输出 remote-ssh-mcp 1.0.0。下载 v1.0.0

WSL 或 Linux 客户端

按使用的客户端选择一条命令。以下示例将主机库放在当前用户的 ~/.local/share/remote-ssh-mcp。如果已有自定义数据目录,两个客户端都填原路径即可沿用原有主机和凭据。

codex mcp add remote-ssh --env REMOTE_SSH_MCP_DATA_DIR="$HOME/.local/share/remote-ssh-mcp" -- "$HOME/.local/bin/remote-ssh-mcp"
claude mcp add --scope user --transport stdio remote-ssh --env REMOTE_SSH_MCP_DATA_DIR="$HOME/.local/share/remote-ssh-mcp" -- "$HOME/.local/bin/remote-ssh-mcp"

Windows 客户端共用 WSL 安装

在 PowerShell 中选择对应命令。将 Ubuntu 替换为安装该包的发行版名。如果发行版的默认用户和安装用户不同,在 --exec 前加上 -u 用户名。WSL 用户的 Bash 登录环境需要能执行 node。

codex mcp add remote-ssh -- wsl.exe -d Ubuntu --exec bash -lc 'REMOTE_SSH_MCP_DATA_DIR=~/.local/share/remote-ssh-mcp exec ~/.local/bin/remote-ssh-mcp'
claude mcp add --scope user --transport stdio remote-ssh -- wsl.exe -d Ubuntu --exec bash -lc 'REMOTE_SSH_MCP_DATA_DIR=~/.local/share/remote-ssh-mcp exec ~/.local/bin/remote-ssh-mcp'

注册后新开客户端会话,调用 ssh_list_hosts 即可查看共享的主机列表。上传和下载的本地文件路径按 WSL 解释,例如 Windows 的 D:\Temp\file.txt 写成 /mnt/d/Temp/file.txt。

服务默认读取 $XDG_DATA_HOME/remote-ssh-mcp,没有设置 XDG 时使用 ~/.local/share/remote-ssh-mcp。REMOTE_SSH_MCP_DATA_DIR 可指定绝对路径或以 ~/ 开头的路径。

Related MCP server: MCP SSH Server

Agent skill

npm 包附带 remote-ssh 操作指引。如需在同一 WSL 用户下启用该 skill,可在安装后运行:

mkdir -p ~/.agents/skills
ln -s "$HOME/.local/lib/node_modules/remote-ssh-mcp/skills/remote-ssh" ~/.agents/skills/remote-ssh

使用

可以让任一客户端添加主机:

{
  "name": "dev",
  "hostname": "192.0.2.10",
  "port": 22,
  "username": "devuser",
  "auth": "password",
  "credential": "example-password"
}

以上是 ssh_add_host 的参数示例。密钥认证使用 auth: "key"、privateKeyPath,加密私钥的口令同样放入 credential。保存成功后返回稳定 host.id 和 host.version;另一客户端下一次 ssh_list_hosts 即可发现,无需重启。已有主机的操作必须用 ID,不能用名称。

凭据直接通过 MCP 输入,默认 remember: true;无需额外页面或终端弹窗。本服务不在结果、错误和诊断日志回显密码,客户端仍可能保存工具输入。远端命令主动输出的内容属于命令输出,可能出现在结果及输出日志中。

remember: false 只在当前 MCP 连接使用。为已有主机临时设置密码不会删除已保存密码;当前 MCP 退出后,下一次连接重新使用已保存资料。临时凭据不能供另一客户端使用。

工具

工具

主要参数与行为

ssh_list_hosts

无参数;返回 ID、版本、配置、凭据是否保存、当前连接状态和工作目录

ssh_add_host

name, hostname, username, auth, port?, privateKeyPath?, jumpHostId?, credential?, remember?

ssh_update_host

hostId, expectedVersion, patch;null 可清除私钥路径或跳板;认证身份变化会清除旧凭据引用,需要重新设置

ssh_delete_host

hostId, expectedVersion;删除后阻止新操作,不强行终止已开始的命令

ssh_test_connection

hostId;独立测试,不改变工作连接和目录

ssh_set_credentials

hostId, expectedVersion, kind: "login" / "sudo", credential?, reuseSshPassword?, remember?

ssh_forget_host_key

hostId, expectedVersion;明确重置信任记录,需先核实服务器身份

ssh_set_workspace

hostId, path?;校验并设置当前 MCP 连接中的远端目录

ssh_shell_exec

hostId, command, sudo?, stdin?, timeoutMs?;默认 120 秒,0 表示不限命令执行时间

ssh_read_file

hostId, path, startLine?, limit?;文本按行读取

ssh_write_file

hostId, path, content, overwrite?

ssh_grep

hostId, pattern, path?, include?, ignoreCase?, limit?;path 是搜索目录,include 过滤文件名

ssh_glob

hostId, pattern, path?, limit?;有界遍历,不递归目录符号链接

ssh_upload_file

hostId, localPath, remotePath, overwrite?

ssh_download_file

hostId, remotePath, localPath, overwrite?

ssh_reset_connection

hostId;重建当前 MCP 的连接并重新校验目录

主机支持多级 jumpHostId 跳板链,拒绝循环;仍被引用的跳板不能删除。普通密码、私钥及仅要求密码的 SSH 交互认证可用;OTP、菜单式堡垒机和 SSH agent 认证不在首版范围内。

sudo 密码单独保存;可传 kind: "sudo", reuseSshPassword: true 明确复用当前 SSH 密码,也可直接传 credential。免密 sudo 不要求密码。缺少或错误凭据立即返回错误;工具不会等待本地弹窗,也不会自动重跑命令。

主机名唯一,改名保持 ID。修改或删除必须带 expectedVersion;冲突返回 HOST_CONFLICT,重新列出后再决定如何修改。地址、账号、认证或跳板配置变化,已有连接返回 HOST_CHANGED,使用 ssh_reset_connection 应用新配置。

生命周期与文件

  • 主机档案、服务器指纹和已记住凭据跨客户端、跨进程重启保存。

  • SSH 连接、每台主机的工作目录和临时凭据只存在于当前 MCP 连接。重启从远端 home 开始。单条命令里的 cd 不改变保存的工作目录。

  • 本地相对路径按 MCP 服务的启动目录解释;上传下载推荐绝对路径。远端支持 ~、~/,不支持 ~other-user。

  • 上传下载按单文件处理,支持二进制;目标是完整文件路径,父目录必须存在,覆盖须 overwrite: true。创建目录、移动和删除文件通过远端命令完成。

  • 输出有界;较大命令输出写入本地私有临时文件,结果返回 fullOutputPath。临时日志不是持久任务记录,不自动过期或删除,需用户或系统清理。

  • 取消和超时尽力结束前台命令。SSH 断开不代表远端已经停止,结果可能为 outcome: "unknown"。不得自动重放这类命令。

  • 命令执行不添加本服务的逐次批准流程;Codex 和 Claude 自身的权限规则仍由客户端控制。

持久化与恢复

remote-ssh-mcp/
  hosts.json                 # 主机、版本、登录与 sudo 凭据引用
  known-hosts.json            # 按地址与端口保存的首次信任指纹
  pending-cleanup.json        # 中断或清理失败后可回收的凭据 ID
  credentials/
    key                      # 本地自动解锁密钥
    vault.json               # AES-256-GCM 加密凭据

采用跨进程锁、锁内重读与原子文件替换。登录与 sudo 引用和主机版本一次提交;先写入新凭据再提交引用,最后清理旧凭据。清理未完成时结果包含 cleanupPending: true,后续管理操作会重试;日志会保护仍被主机引用的凭据。

备份整个数据目录,并保留匹配的 key 与 vault.json。两者同时被取得即可解密,这沿用参考包的自动解锁模式。密钥缺失、权限不正确或库损坏会明确失败,不覆盖旧库或回退到明文。此实现不承诺断电时多个文件具有数据库式事务保证。

首次连接自动记录指纹;后续不匹配则拒绝。只有核实服务器身份后才使用 ssh_forget_host_key,然后重连。重置信任不会重新认证其他客户端已有的连接。

开发与验证

在源码目录下运行以下命令。

npm ci
npm run check
npm run test:integration
npm run test:package

集成测试使用隔离 Docker OpenSSH 容器、临时密钥与数据目录,不使用生产主机。默认从 test/fixture/Dockerfile 构建;如果已有用此 fixture 构建的镜像,可设置 REMOTE_SSH_MCP_TEST_IMAGE=<image>,该外部镜像不会被测试清理删除。

测试覆盖两个真正的 stdio MCP 进程、共享主机、目录隔离、凭据恢复、版本冲突,以及真实 SSH/SFTP、跳板、sudo、超时、取消和网络中断。架构和上游代码来源见 实现设计 和 NOTICE.md。

实际客户端自动验收可单独运行 npm run test:clients。它会调用本机 Codex 与 Claude 的模型,可能产生 API 费用;使用临时主机库和测试容器,不写入已配置的真实主机库。

Available Tools

16 tools
ssh_add_hostA
Destructive

Persist a new uniquely named SSH host shared by Codex and Claude. For password auth provide credential; for key auth provide privateKeyPath and optional credential passphrase. Credentials are remembered by default; remember:false uses this MCP connection only. Returns stable ID and version. No interactive dialog.

Inputs: auth (required), name (required), hostname (required), username (required), +5 more.

ssh_delete_hostA
Destructive

Delete a host and its credentials using expectedVersion. New operations in all clients fail afterward; already-started commands are not forcibly interrupted. Referenced jump hosts cannot be deleted. cleanupPending:true means credential cleanup must be retried by a later management operation.

Inputs: hostId (required), expectedVersion (required).

ssh_download_fileA
Destructive

Stream one remote file to an exact local path via SFTP. Local paths are relative to the MCP server startup directory. Transfers directly without a confirmation dialog. overwrite defaults to false.

Inputs: hostId (required), localPath (required), remotePath (required), overwrite.

ssh_forget_host_keyA
Destructive

Explicitly forget this host endpoint's trusted SSH fingerprint after independently verifying its identity. Next fresh connection records a new fingerprint. Existing connections are not retroactively reverified; reset them explicitly. Never use automatically to bypass a fingerprint mismatch.

Inputs: hostId (required), expectedVersion (required).

ssh_globB
Read-only

Find relative paths through SFTP using glob patterns, including **. Does not recurse into directory symlinks. Results and traversal are bounded.

Inputs: hostId (required), pattern (required), path, limit.

ssh_grepB
Read-only

Search remote file content under a directory using the server's existing grep extended regular expressions. Optional include filters filenames. Output is bounded; no helper is installed remotely.

Inputs: hostId (required), pattern (required), path, limit, +2 more.

ssh_list_hostsA
Read-only

List configured SSH hosts with stable IDs, connection status and this session's per-host working directories. Never returns credentials. All other SSH tools require an explicit hostId; there is no default host.

Inputs: no named parameters.

ssh_read_fileA
Read-only

Read a remote text file through SFTP with 1-based startLine and bounded output. Use ssh_download_file for binary data.

Inputs: path (required), hostId (required), limit, startLine.

ssh_reset_connectionA
Destructive

Reset this session's connection to one host and revalidate its directory. Does not replay commands or guarantee termination of remote processes. Manually disconnected hosts require ssh_set_workspace instead.

Inputs: hostId (required).

ssh_set_credentialsA
Destructive

Set login or sudo credential, remembered by default and shared across clients. remember:false overlays it only for this MCP connection without deleting saved credentials. For sudo explicitly provide credential OR reuseSshPassword:true. Login credential changes require ssh_reset_connection for existing connections. Returns the latest host version; never returns secret values.

Inputs: kind (required), hostId (required), expectedVersion (required), remember, +2 more.

ssh_set_workspaceA
Read-only

Connect or explicitly reconnect one host and set its remote working directory after validation. First connection starts at the login home. Omitting path keeps the current directory. Does not affect other hosts.

Inputs: hostId (required), path.

ssh_shell_execA
Destructive

Execute a command in this host's working directory. Returns stdout, stderr, exitCode and outcome. Default timeout is 120 seconds; 0 disables it. sudo:true runs the entire command as root without an approval dialog; set sudo credentials with ssh_set_credentials when required. Never include passwords in command or stdin. Temporary cd does not change the stored directory. Never replay an unknown outcome automatically.

Inputs: hostId (required), command (required), sudo, stdin, +1 more.

ssh_test_connectionA
Destructive

Test SSH and SFTP with a temporary connection. Does not change this MCP connection's workspace or working SSH connection. Missing credentials fail immediately; set them with ssh_set_credentials.

Inputs: hostId (required).

ssh_update_hostA
Destructive

Update host fields with optimistic version checking. Null clears a jump host or private-key path. Connection identity changes clear saved login/sudo credentials to prevent reuse on a different endpoint; set credentials again. Existing connections require ssh_reset_connection. Rename preserves the ID.

Inputs: patch (required), hostId (required), expectedVersion (required).

ssh_upload_fileB
Destructive

Stream one local file, including binary data, to an exact remote path via SFTP. Local paths are relative to the MCP server startup directory. Transfers directly without a confirmation dialog. overwrite defaults to false.

Inputs: hostId (required), localPath (required), remotePath (required), overwrite.

ssh_write_fileA
Destructive

Write remote UTF-8 text via SFTP using a temporary file. Requires an existing parent directory and explicit overwrite:true to replace a file.

Inputs: path (required), hostId (required), content (required), overwrite.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 16 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action (host CRUD, connection lifecycle, exec, SFTP read/write/transfer, search), and the descriptions explicitly clarify boundaries such as set_workspace vs reset_connection and read_file (UTF-8 text) vs download_file (binary stream). Minor residual overlap exists between ssh_write_file and ssh_upload_file for text files, and between ssh_set_workspace and ssh_reset_connection, both of which reconnect a host.

    Naming Consistency4/5

    All 16 tools share a uniform ssh_ prefix with snake_case and are predominantly verb_noun (ssh_list_hosts, ssh_add_host, ssh_read_file, ssh_download_file). A few deviate from verb_noun — ssh_grep, ssh_glob, and ssh_shell_exec are verb-only or noun+verb — but the pattern remains highly predictable.

    Tool Count4/5

    16 tools is on the heavy side but each earns its place: 6 host-management tools, 4 connection/credential lifecycle tools, 1 exec, and 5 file/search tools. Nothing looks redundant or padded, though the surface is broad enough to be slightly above the ideal sweet spot.

    Completeness4/5

    The surface covers host CRUD with versioning, connection reset/reconnect, credential and host-key management, command execution, text read/write, binary upload/download, and grep/glob search — a full lifecycle for remote SSH work. Gaps are minor: no remote mkdir/remove/stat or directory-listing tool, though these are reachable through ssh_shell_exec and ssh_glob.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables managing multiple remote Linux hosts over SSH via MCP, with command execution, SFTP file operations, and Windows DPAPI-protected credentials.
      10
      1
      MIT