# SSH MCP Server [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/hypnosis/ssh-mcp-server  
**GitHub Stars:** 6  
**npm Downloads (last month):** 778  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ssh-mcp-server

## Description
Modern SSH for AI agents — cloud servers to BusyBox routers, with destructive commands blocked.

## Tools
Capabilities this server exposes over MCP:

- **ssh_exec** — Runs one command or a list of them on a server, each with its own exit code, stdout and stderr. Work measured in minutes belongs in detach, not in a longer timeout. Reach for it last — files, logs, transfers, health and jobs each have a tool that batches the round trips and parses the answer.
- **ssh_file_read** — Reads text files from a server, several of them in one call. A file it could not read is named with the reason, never returned empty or cut short as if that were the content. To look for something inside logs rather than read them, ssh_log_search greps on the server.
- **ssh_file_write** — Writes text files on a server, several in one call, each with its own path, permissions, owner and sudo. A file is replaced whole and never appears half-written; there is no append. For something that already exists on this machine, use ssh_upload.
- **ssh_file_list** — Lists a directory on a server: every entry with its size, mode, owner and modification time, as fields. A directory it was not allowed to enter is named rather than left out, and a listing cut short by the output limit says so. To see what is inside a file, use ssh_file_read.
- **ssh_job_status** — Reports the state of a detached job, with the last lines it wrote so you can see where it got to. lost means no exit code was left behind, not that the work failed — ssh_job_output still has the output.
- **ssh_job_output** — Returns what a detached job has written so far, stdout and stderr together, from a byte offset you choose. For whether the job is still running rather than what it printed, ssh_job_status answers in one line.
- **ssh_job_list** — Lists the detached jobs on a machine with their state, jobs started with sudo included — for when an id was not kept. Ids and states only; for what a job printed, use ssh_job_output.
- **ssh_job_kill** — Stops a detached job and everything it started — the signal reaches the whole process group. A job that had already finished is reported as gone, not as a refusal.
- **ssh_log_tail** — Returns the last lines of one or more log files, whatever their size — nothing is shipped here to be trimmed locally. A container is read by name instead of by path, through the file its driver writes. To look for something rather than read the end, use ssh_log_search.
- **ssh_log_search** — Greps log files on the server and returns the matching lines with their paths, or the paths alone when line bodies are not wanted. An empty answer means no match, never a failed search — files that could not be read are listed apart. For the tail of a file rather than a search through it, ssh_log_tail is cheaper. A container is searched by name instead of by path.
- **ssh_snapshot** — Reports how a machine is doing right now: cpu, memory, disk, containers, listening ports, services and recent errors, in one round trip. Whatever could not be measured comes back null and marked unavailable, never as a zero that reads like an idle machine. For how the machine is set up rather than how it is running, use ssh_audit_baseline.
- **ssh_monitor** — Looks after the SSH connections themselves, not the machines behind them: lists the configured profiles, tests one, reports pool statistics, closes a connection or reloads the profile file. Start here on a machine you have not used yet — test names the state before anything else runs.
- **ssh_upload** — Copies a local file or directory to a server, checked by sha256 on both sides and never left half-written at the target. A directory replaces the target whole — whatever was there and is not in the source is gone with it; merge: true keeps it instead. For text you can paste, ssh_file_write is cheaper; piping base64 through ssh_exec truncates silently.
- **ssh_download** — Copies a file or directory from a server to this machine, checked by sha256 on both sides. To read a text file rather than keep it, ssh_file_read skips the disk.
- **ssh_audit_baseline** — Reports how a machine is set up: sshd, firewall, pending updates, failed services, docker, listening ports and disk, each section marked CRITICAL, WARNING or OK. Reads only, in one round trip instead of a dozen commands. For load and health at this moment rather than settings, use ssh_snapshot.
- **ssh_tls_check** — Checks the TLS certificate a domain serves — days left, whether the name matches a SAN, the issuer and whether renewal is configured — with the handshake made from the server itself, so it sees what that machine sees, including hosts closed to the outside. A null field means the check could not run, not that the certificate is bad. Run it per domain, once ssh_audit_baseline has named the sites.
- **ssh_disk_breakdown** — Finds what filled a disk: free space per filesystem, the largest directories under each path given, and what docker, journald and package caches hold. Reads only, nothing is deleted. For how full the disks are at all, ssh_snapshot answers in one line.
- **ssh_service_status** — Reports one systemd unit: whether it is loaded, active and enabled, with the tail of its journal. A machine without systemd comes back as NOT CHECKED, never as a stopped service — that would read as an outage which is not there. For every failed unit at once, ssh_audit_baseline names them.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ssh-mcp-server": {
    "command": "npx",
    "args": ["-y","@hypnosis/ssh-mcp-server"],
    "env": {
      "SSH_PROFILES_FILE": ""
    }
  }
}
```

**Requires environment variables:** `SSH_PROFILES_FILE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the SSH MCP Server MCP server does

SSH MCP Server MCP server exposes remote administration tasks through MCP tools. It can execute one command or a batch, read and write text or binary files, list directories, and upload or download files and directories. File transfers include integrity checks where supported, and writes use an atomic rename.

The server also covers operational inspection. Agents can request health snapshots, audit baselines, service status, log tails, log searches, TLS certificate details, disk-usage breakdowns, and Docker-related information. Background commands can be detached and then tracked, inspected, or terminated as process groups.

A destructive-command guard applies to command execution. This makes the tool set suitable for workflows where an agent needs server access but should not receive an entirely unrestricted shell interface.

## How it works

SSH MCP Server MCP server delegates connections to the system OpenSSH client rather than bundling its own SSH implementation. Existing keys, SSH configuration, jump hosts, and agent forwarding can therefore be used. When possible, it reuses a multiplexed connection for a destination; older systems may instead require a new connection for each command.

Profiles identify remote machines by host, username, and private-key path. The implementation also accommodates older SSH environments. File transfer can fall back when a remote device does not support the newer transfer protocol, which is relevant for BusyBox routers, NAS devices, and other constrained systems. If a remote machine lacks a hashing utility, the result reports that verification could not be performed rather than asserting a successful check.

## Setup and configuration

The documented runtime requires Node.js 18 or newer and a system `ssh` executable available on `PATH`. The package can be launched with `npx -y @hypnosis/ssh-mcp-server`, or installed globally and started with `ssh-mcp-server`.

Configure the MCP client to run the package over standard input and output. Set `SSH_PROFILES_FILE` to the JSON profile file when it is not using the default location. A profile file contains a `profiles` object; each entry can specify a host, username, and private key path. The example configuration uses `~/.claude/ssh-profiles.json` and a profile named `production`.

Claude Code also supports installing the project as a plugin.

## Tools and capabilities

The available tools include:

- `ssh_exec` for guarded commands, batches, and optional detached jobs.
- `ssh_file_read`, `ssh_file_write`, and `ssh_file_list` for file access and directory listing.
- `ssh_upload` and `ssh_download` for binary-safe file or directory transfers.
- `ssh_job_status`, `ssh_job_output`, `ssh_job_list`, and `ssh_job_kill` for background processes.
- `ssh_log_tail` and `ssh_log_search` for local or container logs.
- `ssh_snapshot`, `ssh_audit_baseline`, `ssh_disk_breakdown`, and `ssh_service_status` for operations checks.
- `ssh_tls_check` for certificate expiry, SAN, chain, and renewal-hook information.
- `ssh_monitor` for connection statistics, reload, testing, listing, and closing transports.

Glob patterns are supported by directory and log operations where documented. Job output can be read from a byte offset, and completed jobs are removed after their configured lifetime.

## Limitations and notes

This tool depends on SSH access and the capabilities of the target machine. Results may be marked as unavailable when a remote utility is missing, and integrity verification is not possible on every host. Modern transfer behavior is not universal, so compatibility fallbacks may open fresh connections or use older protocols.

The material does not describe password-based authentication for Windows profiles, and it does not identify a separate bundled SSH implementation. Operators should therefore ensure that the host OpenSSH client, keys, configuration, and remote permissions are ready before connecting.

_Full upstream README: https://allmcps.com/mcp/ssh-mcp-server/readme_