Mcp Ssh Manager

io.github.bvisible由 GitHub 账号 bvisible 发布v4.3.3更新于 Nov 22, 2026

SSH for AI agents: commands, files, backups and health, with approval, a vault and an audit trail

概览

AI 生成的概览

一个 SSH/SFTP MCP 服务器,让助手在真实服务器上执行命令、传输文件、查询数据库、做备份和健康检查,可选审批与审计。

可以做什么
  • 列出已配置的服务器并执行命令,含 sudo 与持久会话
  • 上传、下载与 rsync 文件,并按权限、备份和重启流程部署
  • 创建、列出、恢复和定时执行 MySQL、PostgreSQL、MongoDB 或文件备份
  • 检查 CPU、内存、磁盘与服务状态,管理进程、跟踪日志并设置告警阈值
  • 导出、导入、列出数据库,并执行只读 SELECT 查询
  • 建立本地、远程与 SOCKS 隧道,并在服务器分组上批量执行同一命令
适用场景
适合让助手在对话中完成真实的服务器运维:排查生产环境变慢、跟踪日志、推送构建产物、部署前备份数据库,或检查多台机器的磁盘。也适合需要对每个服务器设定权限边界并保留代理操作审计记录的团队。
运行要求
以 stdio 在本地运行。使用 npm 需 Node 18 及以上;同步需要 rsync,密码认证同步才需要 sshpass。服务器定义来自 SSH_CONFIG_PATH 指定的 TOML 文件(默认 ~/.codex/ssh-config.toml)或 SSH_ENV_PATH 指定的 .env,也可用命令行添加。桌面版自带运行时。每台主机需要 SSH 密钥或密码。
安装前请注意
这等于把真实机器的 shell 交给代理,默认模式为不受限,应按服务器启用只读或受限模式以及审批。审批、模式和审计只覆盖通过这些工具发起的调用,代理在自己终端里直接运行 ssh 不受约束。保存的密码和口令可放入加密保险库,其密钥绑定单台机器。相关工具可写入、部署、导入数据库和结束进程。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Ssh Manager,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

[图片]

[SSH Manager]

You give your agents a shell,
and you see what they do with it.

An MCP server for SSH. Let Claude Code, Claude Desktop and OpenAI Codex (or any MCP client)
work on your real servers — run commands, move files, query databases, take backups, check health —
and watch over their shoulder while they do it.

[An agent asks to run rm -rf on production; the request is refused; a live command streams its output; every server is probed for health]

Twenty seconds, unedited — watch full size. Real SSH, real SFTP, three throwaway hosts on the loopback.


The problem, in one line

An MCP SSH server is the most dangerous tool you can hand an agent: a shell on machines that matter. Today, when your agent runs something on production, you find out afterwards — if you find out at all.

This one lets you watch, and lets you say no. It is also, on the boring days, simply a very good way to let an assistant do the server work you were going to do yourself.


Choose your workspace

Desktop application (4.3.3): one installation with its own runtime, terminal, file browser and server settings. No separate Node.js or npm installation. Download it:

PlatformFileSignature
macOS, Apple silicon / Intel…-arm64.dmg / …-x64.dmgSigned and notarized by Apple — opens normally
Windows x64 / arm64…-setup.exeNot code-signed yet. Windows shows "Windows protected your PC": More info → Run anyway. Check the file against the SHA-256 in release-manifest-win32.json on the release (ssh-manager app does it for you). Signing comes in a later release.
Linux x64.deb, .AppImageUnsigned, as Linux packages usually are

Already using npm / the CLI? npm update -g mcp-ssh-manager brings 4.3.3, and the V4 engine runs without an interface, from your existing .env, TOML or process variables — no automatic import, no forced wizard, no approval prompt unless you enable one per server. The one behaviour that tightens is SSH host-key verification; read that section of the upgrade and rollback guide before upgrading. To stay on 3.8 for now, pin it: npm install -g mcp-ssh-manager@3.

From the engine to the application in one step. With a V4 engine installed, ssh-manager app downloads the desktop application of the engine's own version, checks it against the release (size and SHA-256 from the release manifest, and on macOS Apple's signature and notarization), installs it and opens it — or just opens it when it is already there. The browser interface of ssh-manager control offers the same as one button. Your agents keep using the npm engine; the application is the window on top of it. Nothing is downloaded unless you ask.

Without npm at all. The application carries the engine too, and your AI tools can start that one: Options → AI tools lists Claude Code, Claude Desktop and Codex, says which ssh-manager each one starts (npm's, the application's, or none yet) and switches it in one click — no Node, no terminal. The same tab, in ssh-manager control, shows npm users which version each tool really runs. A switch rewrites that tool's one ssh-manager entry, keeps its environment variables, and takes effect when the tool next starts; switching back is the same click.

Updates. The application checks for a new version at launch and every six hours and says so where you will see it: a mark on the sidebar, Options → Updates (the running version, the one on offer, a Check now button, release notes) and, once per version, a notification. Downloading is a click, and installing is a second one (Restart to update) or happens when you quit. The npm engine updates with npm, on its own schedule. A change to the interface reaches npm users with the next npm release and application users with the next application release.

Up and running with npm

bash
npm install -g mcp-ssh-manager     # or: brew tap bvisible/mcp-ssh-manager https://github.com/bvisible/mcp-ssh-manager && brew install ssh-manager
ssh-manager server add             # guided: host, user, key or passwordclaude mcp add ssh-manager mcp-ssh-manager

That's it. Restart Claude Code and ask it something.

Using Codex, a source checkout, or a project-scoped install?

OpenAI Codex — same install, then two files. In ~/.codex/config.toml:

toml
[mcp_servers.ssh-manager]command = "mcp-ssh-manager"env = { SSH_CONFIG_PATH = "/Users/you/.codex/ssh-config.toml" }startup_timeout_ms = 20000

And your servers in ~/.codex/ssh-config.toml:

toml
[ssh_servers.production]host = "prod.example.com"user = "admin"key_path = "~/.ssh/id_rsa"default_dir = "/var/www"group = "production"

Everything below works identically from Codex — same 37 tools, same config fields.

From source:

bash
git clone https://github.com/bvisible/mcp-ssh-manager.gitcd mcp-ssh-manager && npm installcd cli && ./install.shclaude mcp add ssh-manager node /absolute/path/to/mcp-ssh-manager/src/index.js

The MCP engine needs no build. To use the interface (ssh-manager control) from a checkout, build it once: npm run build:ui (the published package and the desktop app already carry it).

Scopes — --scope project writes an .mcp.json your team can commit; --scope user enables it everywhere for you.

Prerequisites — Node 18+, on Linux, macOS or Windows. rsync for ssh_sync, sshpass only if you sync with password auth (brew install hudochenkov/sshpass/sshpass, or apt-get install sshpass).


Then just ask

No syntax to learn. Your assistant already knows how to use the 37 tools; you talk to it in your own words.

You sayWhat happens
"Why is production slow right now?"CPU, memory, disk, load average and the top processes, in one round trip
"Back up the database before I deploy."A compressed, timestamped MySQL/PostgreSQL/MongoDB dump with a retention policy
"Tail the nginx error log on staging."Live output, streamed as it happens
"Push ./dist to production:/var/www and restart nginx."The files out, then the restart — with ownership, permissions and a rollback copy handled
"Which of my servers is running out of disk?"Every server in the group, checked in parallel
"Open a tunnel to the production database."Local port forward, so your GUI client just connects
"Run docker ps on everything tagged production."One command, the whole group, sequential or parallel

[The ssh-manager CLI home screen: version, server count, configuration file and desktop app state above the menu]

There is a CLI too, for when you'd rather do it yourself: ssh-manager with no arguments opens this.


Watch over its shoulder — the control plane

New in 4.0.0. The application is opt-in: with no vault and no approval enabled, the engine keeps working headlessly, exactly as 3.8.x. See the migration guide for host-key verification and recovery behaviour.

bash
ssh-manager control          # prints a local URL — or `ssh-manager app` for the desktop app

One thing in two wrappers. ssh-manager control runs the whole interface in a browser tab with nothing extra to install; the desktop builds for macOS, Windows and Linux are that same page with the engine inside them, so they need neither Node nor the npm package.

The interface, desktop menus and notifications support English, Français, 简体中文 and 日本語. Choose Options → Appearance → Language to switch languages. Until you choose, your system or browser language selects the matching one; other languages use English. Your saved choice takes precedence. A new language is three files and one command (npm run lang -- add <code>): see Adding a language.

The desktop build adds the two things a browser tab cannot do:

  • It lives in the menu bar. The icon carries a count when something is waiting, and its menu lists what is blocked on you, which shells and commands are open right now, and your servers — so "is anything waiting on me?" costs a glance instead of a window switch. Closing the window leaves it there rather than quitting.
  • It posts real system notifications, with the application's own identity, so macOS and Windows show and route them properly. Destructive requests stay on screen instead of fading after four seconds. macOS asks your permission the first time it needs to.

[The interface in a browser tab, served by ssh-manager control]

Stop it before it runs

[The Waiting screen: a destructive command from an agent, with Refuse and Approve]

The agent pauses and waits. You see the machine, the user, the tool, and the command in full — wrapped, never truncated, because half a command is how you approve the wrong thing. A desktop notification fires when something is waiting, because the request that goes unseen is the one that times out and is denied.

Approval is switched on from the interface, per server — not from a file:

Servers → the server → Approval → never (default) | destructive | always

Approval is stored in the vault and cannot be overridden by .env or process variables. Editing connection details preserves it. This prevents accidental configuration overrides from disabling the gate; it is not a security boundary against a process that already controls your local user account or vault files. If you had SSH_SERVER_*_APPROVAL set in a file, the engine says so on every start rather than quietly leaving you unprotected.

The destructive list is deliberately short. A prompt that cries wolf gets clicked through without being read, which is worse than no prompt at all: systemctl restart does not interrupt you, systemctl stop does.

When a request requires approval, a timeout, unreachable socket or disconnected control plane denies it. If nothing is listening, start ssh-manager control or the desktop app before retrying. Servers with approval disabled keep working headlessly.

See what it's doing, while it does it

[The Live screen: a command still running, expanded to show its coloured output]

Output goes through a terminal emulator, not a <pre> tag — what your agent ran looks exactly like what you'd have seen had you typed it yourself, colours and all. Each stream keeps a bounded scrollback, so opening the screen mid-command shows what came before instead of starting blank.

Nothing here touches the disk. A stream can carry secrets — a config being catted, a token echoed by a deploy script — so it lives in memory, capped, and disappears with the window.

Both filesystems, side by side

[The file browser: this machine on the left, a server on the right]

Drag a file across and it moves directly between your machine and the server through the control plane. The browser never holds the bytes — which is faster, and the only way a multi-gigabyte file works at all.

Health, when you ask for it

[The Health screen: CPU, memory and disk per server, with a threshold crossed]

Nothing is probed in the background. Each check is an SSH handshake, and a dashboard that connects to every production box on a timer is worse than no dashboard. The button is the whole scheduling policy. Thresholds are yours to set, and crossing one is said in words rather than encoded in a colour.

A shell on any machine

[The Terminal screen: pick a machine to open a shell on, or manage the commands you keep retyping]

Pick a machine, get a shell — the same one an agent gets, with your keyboard on it. Useful for the ordinary reasons, and for the one people ask about most: running an agent on the server rather than pointing one at it.

Including this machine. The desktop application opens a shell on your own computer too, with your login shell and everything you have configured in it, so you are not switching to a different window to run the local half of the same job. Open as many as you like, on any mix of machines: each is a tab across the top and an entry in the rail, and switching away leaves it running.

Beside it, the commands you would rather not retype, saved per server or for all of them, and picked from a list inside any shell.

And the rest of it

[The Servers screen: cards grouped by category]

On the same page: an interactive shell on any server, saved commands you pick from a list instead of retyping, groups you can run one command across, the audit trail of what agents ran and what you decided, and your known host keys.

Every screenshot above is the desktop build; each has a browser twin in docs/images/. See ROADMAP-V4.md for what is built and what isn't.


Safe by default

Other SSH MCP servers hand the agent a shell and wish you luck. This one assumes you'd like some say in the matter.

Decide how far it can go — per server

ModeWhat the agent can do
unrestricted (default)Everything. Same as any other SSH MCP server, zero overhead.
readonlyMutating tools are refused outright — no deploy, no upload, no sudo, no database import. Reads still work.
restrictedEvery command must match an allow pattern and no deny pattern. Anything else is refused before it reaches the host.
env
SSH_SERVER_PROD_MODE=readonlySSH_SERVER_STAGING_MODE=restrictedSSH_SERVER_STAGING_ALLOW_PATTERNS=^systemctl (status|restart) myapp$;^tail -n \d+ /var/log/SSH_SERVER_PROD_AUDIT_LOG=~/.ssh-manager/audit.jsonl

This is a second layer under Claude Code's autoApprove, which is all-or-nothing per tool: once ssh_execute is approved, anything goes. Useful when you're sharing the MCP with a third-party agent, a CI bot, or working on a client's machine. Full reference in docs/SECURITY_MODES.md.

Credentials out of the clear-text .env

bash
ssh-manager vault import      # take what you already have, encryptedssh-manager vault list        # see it, without ever printing a secretssh-manager vault add prod    # add one interactivelyssh-manager vault backup FILE # a copy that survives a new machine

AES-256-GCM, master key in your OS keychain (a 0600 file where there is none — Windows, CI, containers). Only secret values are encrypted: hosts, users and modes stay readable, so the file can still be inspected and diffed. GCM is authenticated, so a tampered vault fails loudly instead of handing a wrong password to a production server.

The key belongs to this machine. A vault copied to a new laptop is ciphertext nobody can open — vault backup writes a copy encrypted under a passphrase you choose, which is what makes the move survivable. Your .env is never modified, not by import, not by the interface, and a setup half in each is a normal state rather than a broken one. Upgrading changes nothing on its own: see docs/MIGRATION.md.

Keep the agent on the tools

Approval, modes and the audit log only see what goes through these tools. An agent that also has a terminal can run ssh prod rm -rf … there and none of it applies. For Claude Code, an opt-in hook closes that door:

bash
ssh-manager guard install        # refuse ssh, scp, sftp and remote rsync in the agent's shellssh-manager guard install --mode ask   # …or ask you each timessh-manager guard print          # show what it would write, change nothingssh-manager guard remove

The agent is told why and which tool to use instead (ssh_execute, ssh_upload, ssh_sync, ssh_tunnel_create). It is a guard against accidents, not a security boundary: it reads the command text. Keep SSH keys and agent sockets away from the account the agent runs as. Nothing is installed unless you run install; it edits only its own entry in ~/.claude/settings.json, and keeps a copy of the file as it was.

The unglamorous parts, which are the ones that bite

  • Your sudo password never reaches the remote command line. It travels on the SSH channel's stdin, so it isn't visible in ps, in /proc/<pid>/cmdline, or in an auditd trail — unlike the echo "$pass" | sudo -S pattern common in this category (#34).
  • Every shell argument is quoted through one central helper, with a test that drives 340 builder × argument × payload combinations through a real shell to prove none of them execute.
  • Read-only SQL is enforced, not suggested. ssh_db_query refuses anything that isn't a SELECT, runs it inside a read-only transaction, and never lets the psql or mysql client read it as a script, where their own commands (\!) would reach a shell. A MySQL query is therefore one line, without backslashes.
  • Vulnerabilities are published, not buried. SECURITY.md has the reporting process and every advisory already fixed — including the six in v3.8.6, among them a command injection on the machine running the server, triggered by any SSH server it connects to.
  • Reproducible installs. The lockfile is committed, CI installs with npm ci, and a test enforces that every dependency resolves to registry.npmjs.org with an integrity hash and no unreviewed install scripts.

Questions people ask

Can I let an AI agent SSH into my servers safely? Yes, if you decide how far it can go. Per server you can make it read-only, allow only commands that match a pattern, or hold every request (or only the destructive ones) until you approve it in the control plane; credentials can live in an encrypted vault instead of a clear-text .env; and every command and decision is logged. See Safe by default.

How do I use Claude Code or Codex with SSH? npm install -g mcp-ssh-manager, add a server with ssh-manager server add, then claude mcp add ssh-manager mcp-ssh-manager. Codex is set up here. Then ask in plain words: "why is production slow?", "tail the nginx error log on staging".

Does it work with Cursor, Windsurf, Cline or another MCP client? It is a standard stdio MCP server, so any MCP client can run it. Claude Code, Claude Desktop and Codex are the clients documented and tested here. For another one, add what it expects, for example:

json
{ "mcpServers": { "ssh-manager": { "command": "npx", "args": ["-y", "mcp-ssh-manager"] } } }

Do I need Node.js? With npm, yes (Node 18 or later). The desktop application carries its own runtime and engine: install it and connect your AI tools from Options → AI tools, with no Node and no npm.

How is this different from other SSH MCP servers? Most hand the agent a shell. This one lets you choose per server how far it goes, can hold requests until you approve them, keeps an audit trail, and has a desktop app and a browser interface to see it all. It also runs without any of that, as a plain engine configured from a .env or a TOML file, if that is what you want.

Where are my passwords and keys kept? Key files stay where they are. Saved passwords and passphrases can go into the encrypted vault (AES-256-GCM, with the key in your operating system's keychain) rather than a .env.

Is it free? Yes, it is MIT-licensed. The source is here, the package is on npm and the desktop apps are on the releases page.


Reference

All 37 tools

Core — always enabled

ToolWhat it does
ssh_list_serversEvery configured server, with its group and mode
ssh_executeRun a command. Falls back to the server's DEFAULT_DIR when no cwd is given
ssh_upload / ssh_downloadMove a single file either way
ssh_syncBidirectional rsync, with real transfer counts

Backup & restore (v2.1+)

ToolWhat it does
ssh_backup_createMySQL, PostgreSQL, MongoDB or files — compressed, with metadata and retention
ssh_backup_listEverything available, with size, date and retention
ssh_backup_restoreRestore one, including across databases
ssh_backup_schedulePut it on cron, with automatic cleanup

See the Backup Guide and examples/backup-workflow.md.

Health & monitoring (v2.2+)

ToolWhat it does
ssh_health_checkCPU, memory, disk, network, uptime, load — with an overall verdict
ssh_service_statusnginx, mysql, docker… on systemd or sysv
ssh_process_managerList, inspect or kill; sort by CPU or memory
ssh_alert_setupThresholds, and what happens when one is crossed
ssh_monitor, ssh_tailLive resource monitoring and log following

Databases (v2.3+)

ToolWhat it does
ssh_db_dumpMySQL, PostgreSQL, MongoDB; optional gzip, optional table subset
ssh_db_importImport a dump, .gz handled automatically
ssh_db_listDatabases, or the tables inside one
ssh_db_querySELECT only — enforced, not suggested (MySQL: one line, no backslash)

Deployment & sessions

ToolWhat it does
ssh_deployFiles out, with permissions, backup and restart handled — see the Deployment Guide
ssh_execute_sudoSudo, with the password on stdin rather than the command line
ssh_session_*Persistent shells that keep their context between commands
ssh_tunnel_*Local, remote and SOCKS forwarding

Organisation

ToolWhat it does
ssh_aliasShort names for servers
ssh_command_aliasShort names for commands you keep retyping
ssh_group_*, ssh_execute_groupRun one thing across many machines
ssh_hooksAutomation hooks around SSH operations — see Aliases and Hooks
ssh_profileSwap whole sets of aliases and hooks — default, frappe, docker, nodejs, or your own
Spending less context — tool groups

All 37 tools cost roughly 43.5k tokens of context. Most people don't need all of them.

bash
ssh-manager tools configure     # interactive wizardssh-manager tools list          # what's on right nowssh-manager tools enable monitoringssh-manager tools disable backup
ModeToolsContextGood for
All (default)37~43.5kThe full set
Minimal5~3.5kJust SSH, and 92% of the context back
Custom5–37variesWhatever you actually use

Groups: core (5, always on) · sessions (4) · monitoring (6) · backup (4) · database (4) · advanced (14).

Fewer tools also means fewer approval prompts and a faster start. ssh-manager tools export-claude writes the matching auto-approval block.

📖 Complete guide →

Bringing servers in from somewhere else

Nobody starts here. You have a ~/.ssh/config with forty hosts, or a FileZilla site manager, or a spreadsheet a colleague sent you.

bash
ssh-manager import ~/.ssh/config          # the format is worked out for youssh-manager import --from transmit        # or read where a tool keeps its listssh-manager import --template servers.xlsx   # or get a form to fill in
SourceHow
Spreadsheet (.xlsx)--template writes one with the columns filled in and three examples to type over
CSVComma or semicolon — Excel writes both, depending on where you live
~/.ssh/configHost, HostName, User, Port, IdentityFile, ProxyJump. Wildcards are skipped, aliases collapse to one server
FileZillasitemanager.xml. SFTP sites only — an FTP bookmark is not an SSH server
PuTTYAn exported .reg. A .ppk key is refused with the puttygen line that converts it
TermiusJSON export, groups included
MobaXterm.mxtsessions, folder becomes the group
TransmitIts favourites, read directly (macOS)

Import is additive. A name you already have comes back as "already configured — left alone", never a silent overwrite; --replace if that is what you want. Two rows with the same name become web and web_2 rather than one.

No password is ever read. FileZilla keeps them base64-encoded, Transmit in the keychain, PuTTY not at all. Copying a credential out of another application's store is not a favour — it moves a secret you had forgotten into a second place you now have to think about. Hosts, users, ports and key paths come across; you are asked for a password once, when you first connect.

Going the other way:

bash
ssh-manager export servers.xlsx     # or .csv, .env, .toml

Exports carry no passwords, no passphrases, no sudo passwords — an export is a file people email each other and commit by accident.

Configuration — every field

Two interchangeable formats, read by the same loader: .env is the usual choice with Claude Code, TOML with Codex (from SSH_CONFIG_PATH, or ~/.codex/ssh-config.toml). Both can coexist — the loader merges them.

env
SSH_SERVER_[NAME]_HOST=hostname_or_ipSSH_SERVER_[NAME]_USER=usernameSSH_SERVER_[NAME]_PASSWORD=password          # or use a keySSH_SERVER_[NAME]_KEYPATH=~/.ssh/keySSH_SERVER_[NAME]_AGENT_PUBLIC_KEY_PATH=~/.ssh/id_ed25519.pub # alternative: select one key from SSH_AUTH_SOCKSSH_SERVER_[NAME]_CERTPATH=~/.ssh/key-cert.pub # optional: OpenSSH certificate for KEYPATHSSH_SERVER_[NAME]_PASSPHRASE=key_passphrase  # optionalSSH_SERVER_[NAME]_PORT=22                    # optionalSSH_SERVER_[NAME]_DEFAULT_DIR=/var/www       # optional working directorySSH_SERVER_[NAME]_SUDO_PASSWORD=…            # optional, for automated deploysSSH_SERVER_[NAME]_DESCRIPTION=…              # optionalSSH_SERVER_[NAME]_GROUP=production           # optional, free-form labelSSH_SERVER_[NAME]_PLATFORM=windows           # optional: linux (default) | windowsSSH_SERVER_[NAME]_PROXYJUMP=bastion          # optional: another server, as jump hostSSH_SERVER_[NAME]_PROXYCOMMAND=…             # optional: ncat, ssh -W, …SSH_SERVER_[NAME]_FORWARD_AGENT=true         # optional, and a real security trade-offSSH_SERVER_[NAME]_ANNOUNCE_AGENT=true        # optional: tell this host an AI agent is driving (off by default)SSH_SERVER_[NAME]_MODE=readonly              # optional: unrestricted | readonly | restricted# Approval is NOT a field here — it is set per server from the control plane and# stored in the vault, so that a shell on one of your machines cannot switch off# the gate that exists to stop it.SSH_SERVER_[NAME]_AUDIT_LOG=~/audit.jsonl    # optional JSONL trail

The same thing in TOML:

toml
[ssh_servers.production]host = "prod.example.com"user = "admin"key_path = "~/.ssh/id_rsa"port = 22default_dir = "/var/www"group = "production"description = "Production server"
[ssh_servers.winhost]host = "192.168.1.90"user = "svc-ssh"key_path = "~/.ssh/winhost_key"port = 2222platform = "windows"
[ssh_servers.internal]host = "10.0.0.5"user = "admin"proxy_jump = "bastion"

Selecting an SSH agent key — use a public key file to select one identity from the existing agent at SSH_AUTH_SOCK, including compatible password-manager agents. The private key stays in the agent, which performs signing. For example:

toml
[ssh_servers.agent_host]host = "example.com"user = "admin"agent_public_key_path = "~/.ssh/id_ed25519.pub"

In the desktop application and the browser interface it is the Agent public key field of the server form, which also closes the password, private key and agent-forwarding inputs while it is set. The .env equivalent is SSH_SERVER_[NAME]_AGENT_PUBLIC_KEY_PATH; the internal configuration field is agentPublicKeyPath. This option fails if the public key file is missing or invalid, the agent is unavailable, or the agent does not offer a matching identity. It cannot be combined with key_path, password, cert_path, or enabled forward_agent; conflicting configuration is rejected. Omitting the option preserves the existing authentication behavior. ssh_sync uses system OpenSSH and does not apply this filter: configure its IdentityFile and IdentitiesOnly yes in your SSH client configuration separately.

OpenSSH user certificates — for servers that trust a certificate authority (TrustedUserCAKeys), point CERTPATH / cert_path at the certificate signed for KEYPATH (usually <key>-cert.pub). It is read on every connection, so a short-lived certificate renewed on disk needs no restart, and a missing file fails the connection instead of falling back to the bare key. It takes effect once ssh2 ships certificate support (mscdex/ssh2#1495); until then the plain key is offered, as before. ssh_sync uses the system ssh, which finds <key>-cert.pub next to the key on its own.

Loading order, highest priority first: process environment → .env → the encrypted vault → TOML. A credential you deliberately put in the vault beats one left in a .env; an operator overriding for a single run still beats both.

Profiles bundle aliases and hooks per project type. Set one with export SSH_MANAGER_PROFILE=frappe, or switch from your assistant, which remembers it in ~/.ssh-manager/profile. Ships with default, frappe, docker and nodejs; add your own in profiles/. Custom aliases and hooks also live in ~/.ssh-manager/, so an upgrade keeps them.

More examples: examples/codex-ssh-config.example.toml.

Getting to machines you can't reach directly

Through a bastion — the tunnel is transparent, every tool works as usual:

env
SSH_SERVER_BASTION_HOST=bastion.example.comSSH_SERVER_BASTION_USER=jumpuserSSH_SERVER_BASTION_KEYPATH=~/.ssh/bastion_key
SSH_SERVER_PRIVATE_HOST=10.0.0.5SSH_SERVER_PRIVATE_USER=adminSSH_SERVER_PRIVATE_PROXYJUMP=bastion

Chains work: if bastion itself has a PROXYJUMP, it's followed recursively. Circular references are detected and rejected.

Through a SOCKS proxy or a custom command — it runs locally and forwards to the host, with %h and %p for host and port:

env
SSH_SERVER_SOCKS_PROXYCOMMAND="ncat --proxy 127.0.0.1:1080 --proxy-type socks5 %h %p"SSH_SERVER_WINPROXY_PROXYCOMMAND="C:\Windows\System32\OpenSSH\ssh.exe -W %h:%p user@jump-host"

Passphrase-protected keys — load the key into ssh-agent and nothing else is needed; SSH_AUTH_SOCK is picked up automatically, the same mechanism plain ssh uses. Storing PASSPHRASE in the config works too, and is the less good option.

Agent forwarding (FORWARD_AGENT=true, off by default, per server) lets a process on the remote host authenticate to other hosts with your local keys — git clone over SSH on a server without copying a private key there.

⚠️ Anyone who can read the forwarded socket on that host — root included — can impersonate you against other hosts for the life of the connection. Only for servers you trust, exactly as ssh_config(5) advises.

Telling your servers an agent is driving (ANNOUNCE_AGENT=true per server, or SSH_MANAGER_ANNOUNCE_AGENT=true for all of them; off by default). Every command channel then carries AI_AGENT=mcp-ssh-manager, following the AI_AGENT over SSH convention, so a host that records it can tell a session an agent drives from one a person drives — SSH cannot otherwise: same key, same user either way. Contributed by @mthamil107 in #84.

  • The server has to accept it. Stock OpenSSH ships AcceptEnv LANG LC_* and drops anything else silently. Add AcceptEnv AI_AGENT to sshd_config and reload; $AI_AGENT is then set for every command and shell the agent runs, for a profile, a wrapper or an audit hook to record.
  • Off by default, for two reasons. Upgrading must not change what reaches your servers. And the request reaches every host whatever its AcceptEnv — sshd only declines to store it — so a host you do not control would learn an agent is on the other end, and could shape its output for one. ANNOUNCE_AGENT=false keeps one host silent under the global switch.
  • Covered: commands, ssh_tail --follow, interactive sessions, and ssh_sync (via SendEnv, supported since OpenSSH 3.9). Not covered: SFTP transfers — ssh2 would fail the whole SFTP session on a server that refuses the variable — and port forwards, which have no environment.
  • A person is never announced. Everything you do from the control plane — a shell, a file, a health probe, a command across a group — is yours, and reaches the server unlabelled.

Groups — tag servers and they become a group, with no extra file to maintain:

env
SSH_SERVER_WEB1_GROUP=productionSSH_SERVER_WEB2_GROUP=production

Groups created with ssh_group_manage live in .server-groups.json and additionally carry execution settings (strategy, delay, stop-on-error). When a name exists in both places, membership is the union and the stored settings apply. Names are case-insensitive. A group that exists only through the group field is read-only for ssh_group_manage — change membership by editing the servers.

When something goes wrong

Claude Code freezes or shows "Interrupted" — almost always an output too large for the context. Output is auto-truncated and the default timeout is two minutes, but you can tune it:

env
MCP_SSH_MAX_OUTPUT_LENGTH=5000    # default 10000 charactersMCP_SSH_DEFAULT_TIMEOUT=180000    # default 120000 msMCP_SSH_COMPACT_JSON=true         # fewer tokens per response

And prefer tail -n 100 huge.log over cat huge.log — the same advice you'd give a colleague.

Tools don't show up — claude mcp list, then restart Claude Code. /mcp inside Claude Code shows the live status.

Connection failed — ssh-manager server test <name> first; it tells you whether it's DNS, the firewall, or the credentials.

Permission denied — check chmod 600 ~/.ssh/your_key, then the username, then what that user is allowed to do on the host.

Still stuck? Open an issue — include the server's PLATFORM and what ssh-manager server test said.

Known limitations, honestly:

  • Command timeouts are advisory. ssh2 can't kill a remote process; on Linux and macOS hosts a timeout wrapper does it properly. On Windows hosts set PLATFORM=windows to skip that wrapper, which OpenSSH for Windows doesn't understand.
  • ssh_sync with password auth needs sshpass. Keys are better anyway. On a Windows host, pass native paths like local:C:\project — drive-letter and UNC paths are converted to MSYS2 form, and a path already written as /c/... is passed through untouched rather than converted twice.
  • Connections are pooled and reused. A stale one reconnects on next use; force it with ssh_connection_status and the reconnect action.
Working on the project
bash
git clone https://github.com/bvisible/mcp-ssh-manager.gitcd mcp-ssh-manager && npm ci./scripts/setup-hooks.sh      # pre-commit checks, including secret detection
npm test                      # 43 suitesnpm run typecheck             # JSDoc through tsc, no build stepnpm run test:all              # both, plus ./scripts/validate.shnpm run test:preview          # isolated candidate fixture, restart and cleanup

The layout:

src/          index.js is the MCP server and its 37 tools; one module per domain              (ssh-manager, config-loader, session-manager, backup-manager,               health-monitor, database-manager, tunnel-manager, server-groups…)cli/          the Bash CLI, plus the Node wrapper that makes it work on Windowsui/           the control plane's React interface (v4)desktop/      the Electron build (v4)profiles/     frappe, docker, nodejs — and room for yoursscripts/      validation, and the rig that regenerates every screenshot and the videodocs/         guides, migration notes, security modes

Pull requests are welcome — CONTRIBUTING.md has the details. Shipping the desktop builds — signing, notarization, and why the Mac App Store is a different product rather than a further step — is in docs/DISTRIBUTION.md.

Nothing in this README's imagery is taken by hand. scripts/demo-env.mjs stands up three real ssh2 servers on the loopback with a seeded vault, a pending approval and a live stream; capture-screenshots.mjs and record-demo.mjs drive Chrome over the DevTools protocol against it; frame-screenshots.py draws the browser and application windows, and macbook-mockup.py draws the laptop. After a UI change, re-run them rather than editing an image.

The hero animation ships twice, light and dark, swapped by <picture> on prefers-color-scheme. A single transparent GIF would have been simpler, but GIF alpha is one bit and transparency defeats its inter-frame compression: the same clip came out at 11.4 MB transparent against 357 KB on a solid ground.


What's new

4.3.3 — a security fix: restricted mode could be made to run a command its allowlist never saw. A comment, a here-document, an ANSI-C quote ($'…') or a parenthesis could hide a command from the check while the shell ran it. The allowlist now reads comments as comments and refuses those constructs, with a reason. Servers in readonly mode and servers without a mode are unaffected; if you use restricted mode, upgrade. Reported by @Fastyyy123 (GHSA-86xm-rv3h-r4f2). See the CHANGELOG.

4.3.2 — a command that fails no longer stays "running" on the Live page. When a call threw instead of returning (a timeout, a dropped connection), or when the engine was closed mid-command, the Live entry read "running" until the control plane restarted. It now ends, as exit -1. Display only: nothing about the commands themselves changes. Found and traced by @TillNano (#159). See the CHANGELOG.

4.3.1 — a security fix: the approval card shows what a deploy or an upload will do. A request without a command line used to read "(no command)", so a deploy could be approved without seeing its files, their target paths or its restart command. The card now shows them. Nothing else changes; upgrade. Reported by @Fastyyy123 (GHSA-vx67-5jmh-4xq2). See the CHANGELOG.

4.3.0 — French and Japanese interfaces, and the agent key in the server form. The interface and the desktop menus now come in Français and 日本語 next to English and 简体中文 (Options → Appearance → Language; the Japanese is @zenk-sugimoto's), and a new language is three files and one command (npm run lang -- add <code>, see Adding a language). The server form has an Agent public key field, so a server can use one identity of your SSH agent without its private key reaching the engine (asked for by @TillNano), and Live and Activity show a command in full instead of cutting it off (@congzhou09). See the CHANGELOG.

4.2.0 — a Chinese interface, a fuller audit log, and a guard against raw ssh. The interface and the desktop menus come in 简体中文 (Options → Appearance → Language; thanks to @xutianhao6). With AUDIT_LOG on, every tool now records what it did, not only a few. ssh_execute can start a long job in the background (background: true, an idea from @SEU-zhc), and the opt-in ssh-manager guard keeps an agent from running ssh in its own shell, where approval and audit do not apply (an idea from @fyq163). Fixed, thanks to @jaredshuai's fork: backups that reported success when the dump had failed (an empty archive, every night from ssh_backup_schedule), a corrupt archive restored in part, MongoDB backups that could not be restored, ssh-manager server remove deleting a look-alike server, editing a server turning read-only into unrestricted, remote tunnels that never worked, a database password in the audit log, and six simultaneous calls opening six connections. ssh-manager codex setup now exists. A tool that fails now sets isError in its reply. See the CHANGELOG.

4.1.0 — choose the agent key per server, and sudo in the audit log. A server can name the one key of your SSH agent it uses, so an agent that holds many keys (a password manager's, say) no longer runs into MaxAuthTries before the right one is offered (thanks to @RebornOnce, #128); with AUDIT_LOG on, ssh_execute_sudo, downloads, group commands and commands sent to a session now record what they did, never the sudo password (#134, thanks to @orshih6, reported by @revert12); llms-install.md lets an agent set the server up for you; dependencies refreshed. Nothing to change on upgrade. See the CHANGELOG.

4.0.3 — a security release; upgrade. ssh_db_query, the read-only tool, could run shell commands on the server through the psql and mysql clients' own commands (\!), including on servers in readonly or restricted mode (GHSA-qmf5-hrhv-5hjm, reported by @orshih6). Every version before it is affected. A MySQL query must now be one line without backslashes. See the CHANGELOG.

4.0.2 — commands reach a Mac, and the desktop terminal is your own. Commands sent to a macOS server no longer fail with timeout: command not found before they start (thanks to Henrik Tilly, #115); the desktop terminal starts a login shell, so what Homebrew installed is found as in Terminal or Warp, and PowerShell on Windows; keystrokes reach the shell in the order they were typed; dependencies refreshed. Nothing to change on upgrade.

4.0.1 — the application tells you about updates. Options → Updates, a mark on the sidebar and a notification once per version, so a new release no longer goes unnoticed in a menu you never open; a tidier Servers toolbar; the interface is built when the package is made rather than committed (what you install is byte for byte the same); and the npm, registry and GitHub descriptions say what V4 is. No change to the engine's behaviour.

4.0.0 — the control plane. See what an agent is running on your servers, with its output, and stop it before it runs. A desktop application for macOS, Windows and Linux, installed from the engine with ssh-manager app; an encrypted vault for credentials; human approval per server; a shell on your own machine alongside the remote ones. Everything new is opt-in — an npm install upgraded from 3.8.x keeps behaving as 3.8.x, which a test installs from the registry and proves. The Windows application is not code-signed in this release. What changes and how to go back.

v3.8.7 — a security release; upgrade. Two advisories fixed: a partial server name or an alias escaped readonly and restricted mode (GHSA-mq9f-5385-rjf4), and ssh_backup_restore's backupId ran commands on the server (GHSA-2wjh-xm9c-7qf9). See the CHANGELOG.

v3.8.6 — a security release; upgrade. Six advisories fixed. The default on-error hook let any SSH server you connect to run a command on your machine; restricted mode only checked how a line started; ssh_db_query could write; host keys were never compared. See the CHANGELOG.

v3.8.5 — a security release. Three command-injection advisories fixed, one of which defeated readonly mode. Upgrade if you use ssh_backup_*, ssh_db_dump, ssh_service_status or ssh_tail.

  • RCE bypassing readonly / restricted (GHSA-m793-whw6-f537) — ssh_service_status and ssh_tail are read-only, so they stay enabled on servers you locked down, and neither quoted its arguments nor consulted the policy layer. A service name like nginx; id > /tmp/pwned executed.
  • RCE through ssh_db_dump (GHSA-796j-h5q5-jx6p) — the stat run after the dump interpolated the output path raw. The v3.6.7 patch had stopped one line short.
  • RCE through every ssh_backup_* tool (GHSA-qwwm-vrm9-4mw8) — backup-manager.js had zero shell escaping across its nine builders while database-manager.js had 95.

Quoting now lives in one module so "did this builder quote its inputs?" has a single answer.

Full changelog, every release back to v1.0.0 →


Documentation · Changelog · Security policy · Roadmap · Issues


Built on the Model Context Protocol, with ssh2 doing the hard part. MIT licensed — see LICENSE.


Made with ❤️ for the Claude Code community



[SSH Manager MCP server]

Also from us

Relais: several Claude accounts on one Mac, one workspace. Switch Claude Desktop and Claude Code between your work and personal accounts in one click, keep every conversation, and see each account's limits. Free and open source, for macOS.

Validation before a release

The V4 testing guide describes the offline suites, real npm 3.8.5 → V4 → rollback checks, browser flows, and platform release gates. Use the final V4 test guide to review the actual npm package or desktop candidate with a disposable profile before publication.

来源:README.md,提交 47fb5c6

工具

37

ssh_execute

Runs a shell command over SSH on a named configured server and returns stdout, stderr, and exit code. Mutates remote state depending on the command; not read-only. Expands command aliases before running. Uses the cwd parameter or, if omitted, the server configured default directory; adapts syntax for Linux versus Windows PowerShell targets. Timeout defaults to 120000 ms and is capped at 300000 ms. Under readonly mode destructive commands like rm or dd are refused; under restricted mode the command must match allow patterns. Output is truncated when very large. For a job that outlives the timeout (a training run, a long build) set background to true instead of using nohup yourself: it starts the command detached and returns at once with its pid and the log file it writes to; read that file with ssh_tail (follow: false) and check or stop the job with ssh_process_manager.

输入参数cwdserver必填command必填timeoutbackground

ssh_upload

Uploads one local file to a remote destination path over SFTP on the named server, overwriting any existing remote file at that path. Mutates remote state and is not idempotent beyond replacing the target. Creates no backup. Requires the local file to exist. Does not use sudo, so the remote path must be writable by the configured SSH user. This tool is blocked entirely on servers set to readonly or restricted security mode. For directory trees use ssh_sync instead.

输入参数server必填localPath必填remotePath必填

ssh_download

Downloads one remote file from the named server to a local destination path over SFTP, overwriting any existing local file at that path. Affects only the local filesystem and is read-only on the remote side, so it stays allowed even on servers in readonly or restricted security mode. Reads the remote file using the configured SSH user, which must have permission to read it. Handles single files only; use ssh_sync for directories.

输入参数server必填localPath必填remotePath必填

ssh_sync

Synchronizes files or directories between local and remote using rsync over SSH on the named server. Each of source and destination must carry a local: or remote: prefix and one side must be local and the other remote; with no prefix it assumes a push from local to remote. On Windows MCP hosts, provide native Windows local paths such as C:\project or .\project; the tool converts drive-letter and UNC paths to MSYS2 format before spawning rsync. Do not pre-convert a local path to /c/project because Node performs local filesystem checks using Windows path semantics. Mutates the destination. Setting delete true removes destination files absent from source, which is destructive; dryRun true previews without changing anything. Compression is on by default. Password authentication requires sshpass installed locally. Blocked on readonly or restricted servers. Timeout defaults to 30000 ms.

输入参数deletedryRunserver必填source必填excludetimeoutverbosechecksumcompressdestination必填

ssh_tail

Reads the tail of a remote log file on the named server, optionally filtered by a grep pattern. Read-only; it does not modify remote state. Behavior depends on follow, which defaults to true: in follow mode it starts a streaming tail whose output is written to the server process stderr rather than returned, and the response only reports a session note, so to capture content directly set follow to false to get the last N lines back. The lines parameter defaults to 10.

输入参数file必填greplinesfollowserver必填

ssh_monitor

Collects a read-only snapshot of system resources on the named Linux server by running inspection commands such as top, free, df, ss, and ps. The type parameter selects the view and defaults to overview; other values are cpu, memory, disk, network, and process. Does not change remote state and needs no sudo. The interval and duration parameters are accepted for continuous monitoring intent but a single snapshot is gathered. Targets Linux tooling, so output may be empty on Windows hosts.

输入参数typeserver必填durationinterval

ssh_history

Returns the in-memory log of SSH commands previously run through this server process during the current session, formatted with timestamps, server, duration, and success status. Purely local and read-only: it opens no SSH connection and does not persist across restarts. Optional filters narrow the results by server name, by success or failure, and by a search substring in the command text; limit defaults to 20 most recent entries. Does not expose command output, only the commands and their outcomes.

输入参数limitsearchserversuccess

ssh_session_start

Opens a new persistent interactive shell on the named configured server and returns a generated session ID. Stateful and side-effecting: it establishes (or reuses pooled) SSH connection and keeps an open shell that preserves working directory, environment, and command history across later ssh_session_send calls, unlike one-shot ssh_execute. The optional name is only a human label. The session stays open and consumes a remote shell until ssh_session_close is called.

输入参数nameserver必填

ssh_session_send

Runs one command inside an already-open session identified by its session ID, reusing the persisted working directory, environment, and history of that shell. Mutates remote state like any shell command and is not idempotent; cd and export update the saved context for subsequent calls. Commands run through a bash-style shell (Unix-oriented). The security policy of the underlying server is enforced, so readonly or restricted servers may refuse. Default timeout is 30000 ms.

输入参数command必填session必填timeout

ssh_session_list

Lists currently active SSH sessions with their ID, server, state, working directory, command count, age, idle time, and any defined variables. Read-only: it inspects in-memory session state and changes nothing on remote hosts or local config. The optional server argument is a case-insensitive substring filter on server name; omit it to list every active session. Closed sessions are excluded from the results.

输入参数server

ssh_session_close

Terminates an open SSH session given its session ID, writing exit to the remote shell, ending it, and discarding its in-memory history and context; the session ID becomes unusable afterward. Destructive to session state but does not delete remote files. Passing the literal value all closes every active session at once, ignoring individual close errors. It does not drop the pooled underlying connection, only the interactive shell.

输入参数session必填

ssh_execute_group

Runs one command on every server belonging to the named group and returns a per-server success or failure report. Members come from the groups defined with ssh_group_manage plus every server whose configuration carries a matching group field, so a group can exist through the config alone. Mutates remote state on each member and is not idempotent. Best-effort: the security policy of each server is evaluated independently, so readonly or restricted members are reported as failed without aborting the rest unless stopOnError is set. Strategy may be parallel, sequential, or rolling (delay applies between servers). Per-server timeout is 30000 ms; cwd defaults to the default_dir of each server.

输入参数cwddelaygroup必填command必填strategystopOnError

ssh_group_manage

Creates, updates, deletes, and inspects named server groups used by ssh_execute_group, persisting changes to local configuration only with no remote side effects. The action selects the operation: create, update, delete, add-servers, remove-servers, or list. Every action except list requires name; add-servers and remove-servers also require a non-empty servers array. list is read-only and also reports the groups derived from the per-server group field of the SSH configuration, which are read-only here and change only by editing that configuration. Optional strategy, delay, and stopOnError set default group execution behavior.

输入参数namedelayaction必填serversstrategydescriptionstopOnError

ssh_list_servers

Lists all SSH servers defined in the loaded configuration, returning for each the name, host, user, port, authentication type (password or key), default directory, group, and description. Read-only and local: it reads configuration only and opens no SSH connections. Deliberately omits secrets, so no passwords, key paths, passphrases, or sudo passwords are returned. Takes no parameters. Useful as a first call to discover which server names other tools accept.

无需输入参数。

ssh_deploy

Deploys a list of local files to remote paths on the named server, uploading each to a temporary location first and then moving it into place. Mutates remote state. By default it backs up any existing target file before overwriting; backup can be disabled per call. Options can set owner and permissions, supply a sudo password, and give a shell command to run afterward (restart, for example "sudo systemctl restart nginx"), which runs as written on the server as the SSH user and is shown in full to whoever approves the deploy. Detects sensible owner and permission defaults from the remote path. Runs pre and post deploy hooks. Blocked entirely on servers in readonly or restricted security mode.

输入参数files必填server必填options

ssh_execute_sudo

Runs a command with elevated privileges via sudo on the named server and returns the exit code and output. Prepends sudo when absent. If a password is given, or a sudo password is configured for the server, it is piped to sudo -S and masked in the returned output. Mutates remote state and can be destructive. Honors the cwd parameter or the server default directory and adapts to Linux or Windows. Timeout defaults to 30000 ms. Blocked entirely in readonly mode; in restricted mode the command must satisfy the allow and deny patterns.

输入参数cwdserver必填command必填timeoutpassword

ssh_command_alias

Manages local shorthand aliases that map a short name to a full command string, stored in local config with no remote execution or side effects. The action selects behavior: add (requires both alias and command), remove (requires alias), list to show all aliases tagged as profile or custom, or suggest to return existing aliases matching a search term passed in the command field. Adding an existing alias overwrites it.

输入参数aliasaction必填command

ssh_hooks

Manages automation hooks that fire around SSH operations such as pre-deploy, toggling them on or off in local configuration only with no immediate remote action. The action selects behavior: list shows each hook with its enabled state, description, and action count; enable and disable flip a hook and both require the hook name; status summarizes which hooks are currently enabled versus disabled. Toggling persists and affects later operations.

输入参数hookaction必填

ssh_profile

Manages SSH Manager profiles that bundle command aliases and hooks for different project types, affecting local configuration only with no remote side effects. The action selects behavior: list shows available profiles and the active one, current shows the active profile details, and switch activates a named profile and requires the profile argument. A successful switch reports that Claude Code must be restarted before the new profile takes effect.

输入参数action必填profile

ssh_connection_status

Inspects and manages the pooled SSH connections held by this server process; affects only local in-memory connections, never remote state. The action parameter selects: status lists active connections with age and keepalive (read-only); reconnect closes then reopens one connection; disconnect closes one connection; cleanup drops aged-out and dead connections. The server parameter is required for reconnect and disconnect and ignored otherwise.

输入参数action必填server

ssh_tunnel_create

Opens a new SSH connection to the named server and starts a port-forwarding or SOCKS proxy tunnel that keeps running until closed. The type parameter selects local forward, remote forward, or dynamic SOCKS5 proxy. localPort is always required; remoteHost and remotePort are required for local and remote types but ignored for dynamic. localHost defaults to 127.0.0.1. Returns a tunnel ID used later to close it.

输入参数type必填server必填localHostlocalPort必填remoteHostremotePort

ssh_tunnel_list

Lists currently active SSH tunnels tracked by this process, showing each tunnel ID, server, type, state, local and remote endpoints, active and total connection counts, bytes transferred, error count, and timestamps. Read-only: it does not create, modify, or close anything. The optional server parameter filters results to one server; omit it to list every active tunnel across all servers.

输入参数server

ssh_tunnel_close

Tears down active SSH tunnels created earlier, freeing the bound local ports; this affects only local tunnel state, not the remote host. Exactly one of tunnelId or server must be supplied: tunnelId closes that single tunnel, while server closes every tunnel for the named server and reports how many were closed. Supplying neither raises an error. Closing is final and cannot be undone.

输入参数servertunnelId

ssh_key_manage

Manages SSH host key fingerprints in your local known_hosts file for the named server. The action parameter selects: verify, check, and list are read-only comparisons or listings; accept adds or updates the host key in known_hosts; remove deletes it. accept and remove mutate local state and are blocked on servers configured as readonly. server is required for every action except list. autoAccept defaults to false and should be used with caution.

输入参数action必填serverautoAccept

ssh_alias

Manages local name aliases that let you reference a configured server by a shorter or alternative name. The action parameter selects add, remove, or list. add creates an alias pointing to an existing server and requires both alias and server; remove deletes an alias and requires alias; list shows all aliases (read-only). add and remove persist the alias mapping locally. The target server must already exist for add to succeed.

输入参数aliasaction必填server

ssh_backup_create

Creates a database or file backup on the remote server over SSH, writing a compressed archive plus a JSON metadata file into backupDir. Supports mysql, postgresql, mongodb, and files (full is not yet implemented and errors). Database types require database; files requires paths. After writing it prunes backups older than retention days (default 7); compress defaults to true. Runs pre-backup and post-backup hooks.

输入参数name必填type必填pathsdbHostdbPortdbUserserver必填excludecompressdatabasebackupDirretention另有 1 个

ssh_backup_list

Lists existing backups found in backupDir on the remote server, returning each backup id, type, database or paths, size, compression, retention, status, and creation time parsed from stored metadata. Read-only: it inspects the filesystem and mutates nothing. Optional type filters results to mysql, postgresql, mongodb, files, or full. backupDir defaults to the configured backup directory.

输入参数typeserver必填backupDir

ssh_backup_restore

Restores a previously created backup identified by backupId, reading its metadata to pick the engine. This is destructive and overwrites the target: PostgreSQL runs pg_restore with --clean --if-exists which DROPs existing objects, MongoDB runs mongorestore --drop, and MySQL pipes the dump into the live database replacing matching objects. Supports mysql, postgresql, mongodb, and files. Runs pre-restore and post-restore hooks.

输入参数dbHostdbPortdbUserserver必填backupId必填databasebackupDirdbPasswordtargetPath

ssh_backup_schedule

Schedules a recurring backup on the remote server by writing an executable bash script to /usr/local/bin/ssh-manager-backup-NAME.sh and installing a crontab entry for the given cron expression. Mutates the remote filesystem and crontab, and typically needs root to write that path. Supports mysql, postgresql, mongodb, and files; the generated script also deletes backups older than retention days (default 7).

输入参数name必填type必填pathsserver必填databaseschedule必填retention

ssh_health_check

Runs a comprehensive read-only health check on the named server by executing diagnostic shell commands over SSH, then returns parsed JSON with overall status, CPU, memory, disk usage, and uptime. It only reads metrics and changes nothing on the remote host. Set detailed to true to additionally include load average and network metrics; it defaults to false. Critical CPU, memory, or disk conditions are surfaced in a critical_issues list.

输入参数server必填detailed

ssh_service_status

Checks the running state of the named system services on a remote server by querying each one over SSH, returning JSON per service plus running and stopped counts and an aggregate health rating. Read-only: it inspects status without starting, stopping, or restarting anything. The services array parameter is required and lists the service names to check, for example nginx, mysql, or docker; common names are resolved to their actual unit names automatically.

输入参数server必填services必填

ssh_process_manager

Lists, inspects, or terminates processes on a remote server over SSH. The action parameter selects: list returns top processes (read-only), info returns details for one process (read-only), and kill sends a signal to terminate a process and mutates remote state. pid is required for kill and info. kill is blocked on servers configured as readonly. signal defaults to TERM, sortBy defaults to cpu, and limit defaults to 20; filter narrows the list by name or command.

输入参数pidlimitaction必填filterserver必填signalsortBy

ssh_alert_setup

Configures and evaluates CPU, memory, and disk usage alert thresholds for a remote server. The action parameter selects: set writes the threshold config to /etc/ssh-manager-alerts.json on the remote host (mutating, may need write access to /etc, and is blocked on readonly servers); get reads back that config; check reads current metrics and compares them to stored thresholds. get and check are read-only. enabled defaults to true; check errors if no config exists yet.

输入参数action必填server必填enabledcpuThresholddiskThresholdmemoryThreshold

ssh_db_dump

Dumps a database to a file on the remote server over SSH; it reads data only and does not modify the database. Supports mysql (using --single-transaction --routines --triggers), postgresql (custom format with --clean --if-exists, restorable via pg_restore), and mongodb. compress defaults to true and gzips the output. The optional tables list applies to MySQL and PostgreSQL only and is ignored for MongoDB.

输入参数type必填dbHostdbPortdbUserserver必填tablescompressdatabase必填dbPasswordoutputFile必填

ssh_db_import

Imports a dump file into a target database on the remote server and is destructive to existing data. PostgreSQL uses pg_restore --clean --if-exists which DROPs existing objects before loading; MongoDB uses mongorestore with --drop controlled by the drop flag (default true); MySQL pipes the file into the live database, replacing objects defined in it. Supports mysql, postgresql, mongodb. Compressed .gz inputs are decompressed automatically.

输入参数droptype必填dbHostdbPortdbUserserver必填database必填inputFile必填dbPassword

ssh_db_list

Lists database objects on the remote server for the given engine without modifying anything. When database is provided it lists the tables (SQL) or collections (MongoDB) of that database; when omitted it lists all databases with common system databases filtered out. Supports mysql, postgresql, and mongodb. Returns the items and a count. Read-only and safe to call repeatedly.

输入参数type必填dbHostdbPortdbUserserver必填databasedbPassword

ssh_db_query

Runs a read-only query against a remote database. For mysql and postgresql it is strictly limited to one SELECT statement: the query must begin with SELECT, and INTO, file functions, and any insert, update, delete, drop, create, alter, truncate, grant, revoke, or exec keyword are rejected before execution; it then runs inside a read-only transaction, so the database itself refuses any write. For mongodb it runs a find() and requires the collection parameter; the query must be a filter document (JSON or mongo shell syntax such as ObjectId("…")), and $where, $function and $accumulator are refused. Returns the raw command output as text.

输入参数type必填query必填dbHostdbPortdbUserserver必填database必填collectiondbPassword

版本历史

11
  1. v4.3.3最新Nov 22, 2026
  2. v4.3.2Nov 21, 2026
  3. v4.3.1Nov 21, 2026
  4. v4.3.0Nov 19, 2026
  5. v4.2.0Nov 14, 2026
  6. v4.1.0Nov 13, 2026
  7. v4.0.3Nov 5, 2026
  8. v4.0.2Nov 1, 2026
  9. v4.0.1Oct 26, 2026
  10. v4.0.0Oct 26, 2026
  11. v3.8.5Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分