remote-ssh-mcp
Remote SSH MCP server for operating on hosts defined in ~/.ssh/config, exposing tools for command execution, file management, Docker/system diagnostics, HTTP probing, and x-ui panel API calls.
Run arbitrary shell commands on a remote host, with timeouts and output caps.
Read remote text files, optionally by line range.
Write or append remote files verbatim, with atomic replacement and automatic backups.
Back up remote files or directories as
tar.gzwith asha256file.List Docker containers, execute commands inside containers, and tail container logs.
Collect a Linux system snapshot: memory, root disk, load, and listening TCP ports.
Check systemd unit status and recent journal lines.
Probe URLs from a host, optionally through a proxy, reporting HTTP status, timing, and egress IP.
Call x-ui/3x-ui panel APIs with the bearer token injected remotely.
Runs operations against Docker on remote hosts: lists containers (optionally including stopped ones, with regex filtering), executes commands inside a container with automatic quoting, and tails merged stdout/stderr logs with tail/since options. Commands can also be run in a container through the generic exec tool.
Targets remote Linux servers defined in ~/.ssh/config: runs shell commands (single, batched, or across multiple hosts), transfers scripts/SQL via stdin, manages long-running background jobs, reads and writes/modifies files with automatic backups, and gathers systemd unit status with journal lines, memory/disk/load/listening-port snapshots, HTTP reachability with egress IP, and x-ui panel API calls.
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., "@remote-ssh-mcp check memory, disk, and load on web1"
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.
remote-ssh-mcp
给 AI agent 用的远程运维工具,是一个 MCP 服务。agent 只要说出 ~/.ssh/config 里的主机别名,比如 web1,就能在那台服务器上跑命令、查容器、改配置、看服务状态,效果等同于 ssh web1 …,但不用 agent 自己拼 ssh 命令和多层引号。
能做什么
在
~/.ssh/config里配好的任意主机上跑命令,结果直接返回给 agent。一次调用同时跑几条互不依赖的命令,或在几台主机上同时跑同一条命令,结果按标签分段返回。
脚本和数据经标准输入传过去,在容器里跑命令,在 Windows 主机上跑 PowerShell,都不需要 agent 自己处理多层引号。
写远端文件或只改其中几处,会覆盖前自动备份到
~/ops-backups/。把一台主机上命令的输出直接接到另一台主机的命令上,或把本机文件推到主机上,数据不落本机磁盘。
非 root 账号也能以 root 身份运行命令,sudo 要密码时由 agent 传入。
输出里的密码、token 默认打码。
重启关机、装包卸包这类危险命令默认拦下,并提示 agent 让用户手动执行。
Related MCP server: ssh-for-agents
工具一览
工具 | 做什么 | 默认出现 |
| 跑任意命令 | 是 |
| 覆盖、追加或局部修改文件,覆盖和修改前自动备份 | 是 |
| 在主机之间搬数据,或把本机文件推到主机上 | 是 |
| 调用 x-ui / 3x-ui 面板接口 | 否 |
| 重启主机并等它回来 | 否 |
| 从本机调用 Cloudflare API | 否 |
默认不出现的工具,要用时在环境变量 SSH_MCP_TOOLS 里写上,如 exec,file_write,pipe,xui_api。
每个工具的参数、例子和返回格式见 docs/tools.md。
适用范围
适合在
~/.ssh/config里配好的 Linux 主机上排查问题、改配置。Windows 主机用
exec加shell(可用SSH_MCP_HOST_SHELLS设成默认),其余工具都按 Linux 命令写。Windows PowerShell 5.1 和 pwsh 7 已在 Windows 11(Win32-OpenSSH,默认 shell 为 Git Bash)上实测过。
需要交互式终端的操作(
top、vim)请直接开 ssh。
环境要求
Node.js 20 或更新。
本机装有 OpenSSH 客户端,
~/.ssh/config里配好主机别名,并且能用密钥免密登录。
安装
把下面的配置加进你的 MCP 客户端,npx 会自动下载最新版:
{
"mcpServers": {
"remote-ssh": {
"command": "npx",
"args": ["-y", "@arcdent/remote-ssh-mcp"]
}
}
}想固定版本就写成 @arcdent/remote-ssh-mcp@0.3.0。从源码运行时,先在仓库里 npm install(会顺带构建),再把配置改成 "command": "node"、"args": ["/path/to/remote-ssh-mcp/dist/index.js"]。
claude mcp add remote-ssh -s user -- npx -y @arcdent/remote-ssh-mcp要放开某类危险命令时加 -e,如 claude mcp add remote-ssh -s user -e SSH_MCP_ALLOW_PKG=1 -- npx -y @arcdent/remote-ssh-mcp。
把上面的配置加进 ~/.cursor/mcp.json。要放开某类危险命令时,在 remote-ssh 里加 "env": { "SSH_MCP_ALLOW_PKG": "1" }。
装好后可以先在仓库里试一次调用,看到的就是 agent 拿到的结果。
npm run call -- exec '{"host":"web1","cmds":{"disk":"df -h / | tail -1","load":"uptime","bad":"exit 3"}}'== disk exit=0
/dev/vda1 30G 2.1G 27G 8% /
== load exit=0
03:49:36 up 10 days, 3:55, 0 user, load average: 0.00, 0.02, 0.00
== bad exit=3配置
用环境变量配置,写在客户端配置的 env 里(Claude Code 用 -e)。
环境变量 | 说明 |
| 默认不设,只暴露 |
|
|
| 主机的默认 shell,逗号分隔的 |
| 默认不设,拦截重启、关机这类电源类命令,设为 |
| 默认不设,拦截装包、卸包这类命令,设为 |
具体拦哪些命令,以及其他安全细节,见 docs/tools.md 的「危险命令拦截」和「安全」两节。
开发
npm install
npm run build
npm test
npm run call -- --list
npm run call -- exec '{"host":"web1","cmd":"uptime"}'npm run call 用来在本地直接调用工具,运行前要先 npm run build。
许可证
MIT,详见 LICENSE。
Available Tools
3 toolsexecB
在主机上执行命令,效果同 ssh <host> '<cmd>';cmd 不用带最外层的引号。可用主机:
Inputs: host (required), cmd, cmds, conn, +8 more.
file_writeA
把 content 原样写进远端文件(不用转义),或用 edits 改其中几处。overwrite 和 edits 先把旧文件备份到 ~/ops-backups/-auto/,再原子替换,保留权限和属主;append 追加到文件末尾。
Inputs: host (required), path (required), conn, mode, +5 more.
pipeA
把来源的数据直接接到主机上命令的标准输入,效果同 ssh A '<cmd>' | ssh B '<cmd>',数据只经过本机内存、不落盘。如 from {"host":"a","cmd":"tar -C /etc -cf - nginx"}、to {"host":"b","cmd":"tar -C /etc -xf -"}。两端各自可带 sudo、pswd、conn,用法同 exec。返回两端的退出码、传输的字节数和 sha256。
Inputs: to (required), from (required), redact, timeout, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools cover distinguishable primitives: command execution, remote file writing, and host-to-host piping. file_write partially overlaps with what exec could do via shell redirection, but its atomic write/backup/edit features make the intended use clear.
Names mix styles: exec is a bare verb abbreviation, file_write is a noun_verb compound, and pipe is a noun. All are lowercase and readable, but there is no predictable verb_noun convention across the set.
Three broad, composable primitives are well-scoped for a remote SSH server; each tool earns its place and exposes many parameter combinations. The set stays focused rather than fragmenting operations into many narrow tools.
Core operations are covered: command execution, file writing/editing with backups, and streaming between hosts. Dedicated file-read, file-delete, and local-to-remote transfer tools are absent, but exec can serve as a workaround for most of these gaps.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to securely execute shell commands on remote SSH servers with granular per-host permission controls. Automatically discovers hosts from ~/.ssh/config and exposes dedicated tools for each allowed host to ensure proper authorization before remote execution.19,226 npmApache 2.0
- AlicenseAqualityDmaintenanceEnables AI agents to execute SSH commands, read files, and list directories on remote hosts with a configurable command-safety policy.5MIT
- AlicenseAqualityBmaintenanceEnables AI agents to securely connect to and manage remote servers via SSH, with tools for running commands, file operations, log inspection, service management, and system monitoring under configurable access controls and audit logging.1219 npm1MIT
- AlicenseAqualityBmaintenanceEnables AI agents to safely access and administer remote machines over SSH using existing OpenSSH config, with typed tools for running commands, reading and writing files, listing directories, and retrieving file metadata.928 npmMIT