# tufantunc/ssh-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/tufantunc/ssh-mcp  
**GitHub Stars:** 840  
**npm Downloads (last month):** 34244  
**Views:** 9  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tufantunc-ssh-mcp

## Description
MCP server exposing SSH control for Linux and Windows servers via Model Context Protocol. Securely execute remote shell commands with password or SSH key authentication.

## Tools
Capabilities this server exposes over MCP:

- **list-connections** — Discover available hosts and connection status
- **list-sessions** — List active sessions per host
- **open-session** — Create a named interactive (stateful) or background session
- **close-session** — Close a session. A background session's command is signalled (INT/TERM/KILL) before its channel is dropped
- **read-session-output** — Read output from background sessions (e.g., `tail -f`)
- **read-command** — Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...)
- **run-command** — Execute arbitrary commands (destructive/privileged need approval, unless `approvalPolicy = "auto"`)
- **privileged-command** — Execute with sudo (needs approval, unless `approvalPolicy = "auto"`)
- **sftp-upload** — Upload a file via SFTP (replaces the destination unconditionally)
- **sftp-download** — Download a file via SFTP
- **sftp-list** — List a remote directory, bounded in entries and bytes
- **sftp-upload-file** — Stream a local file to the remote host, never through model context
- **sftp-download-file** — Stream a remote file to local disk, never through model context
- **signal-process** — Send INT/TERM/KILL to a remote PID
- **reload-config** — Show the config file's status, or re-read and apply it without a restart (see [Reloading](#reloading))

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

```json
"mcpServers": {
  "ssh-mcp": {
    "command": "npx",
    "args": ["-y","ssh-mcp"],
    "env": {
      "SSH_MCP_PASSWORD": "",
      "SSH_AUTH_SOCK": ""
    }
  }
}
```

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

## Documentation

## What tufantunc/ssh-mcp does

SSH access is exposed as MCP tools for remote Linux and Windows administration. Agents can discover configured hosts, inspect active sessions, run read-only or arbitrary commands, use sudo through a separate privileged operation, signal remote processes, and transfer files over SFTP.

The server separates lower-risk inspection from operations that can change a system. Read-only commands are restricted to an allowlist, while arbitrary, privileged, destructive, and file-writing actions can require human approval. Configuration determines the hosts, roles, and approval behavior available to the MCP client.

## How it works

Install the package globally with `npm install -g ssh-mcp`, then start the `ssh-mcp` command through an MCP client. The server communicates over the standard MCP stdio transport in the documented client examples. Claude Code uses `claude mcp add --transport stdio ssh-mcp -- ssh-mcp`; Claude Desktop, Cursor, and Windsurf can invoke the command from an MCP server configuration.

A TOML configuration defines named profiles with a host, port, user, authentication method, key reference, role, and approval policy. Profiles can use password authentication through `SSH_MCP_PASSWORD` or an SSH agent through `SSH_AUTH_SOCK`. The server can start before configuration exists so clients can complete discovery, but tool calls are refused until a valid configuration is available. The `reload-config` tool can apply a newly written file without a restart.

## Setup and configuration

Configuration paths are platform-specific:

- Linux: `~/.config/ssh-mcp/config.toml`, or the equivalent under `$XDG_CONFIG_HOME`
- macOS: `~/Library/Application Support/ssh-mcp/config.toml`
- Windows: `%APPDATA%\\ssh-mcp\\config.toml`

A profile includes values such as `host`, `port`, `user`, `auth`, `keyRef`, `role`, and `approvalPolicy`. The example configuration uses a non-root deployment account and a key at `~/.ssh/id_ed25519`. Do not point the server at a root account, and do not use automatic approval for production profiles.

On Linux and macOS, the server checks permissions on both the configuration file and its directory. Windows uses ACL checks: write access from another account is refused, while read exposure is reported unless stricter ACL handling is enabled. The `--strictConfigAcl` and `--allowUncheckedConfigAcl` flags change how ACL findings are handled.

Store passwords in `SSH_MCP_PASSWORD`, not command-line arguments. SSH agent authentication uses `SSH_AUTH_SOCK`. The documented permission commands set the configuration directory to mode 700 and the file to mode 600 on POSIX systems.

## Tools and capabilities

- `list-connections` discovers configured hosts and their connection status.
- `list-sessions` shows active sessions for each host.
- `open-session` creates a named interactive stateful session or a background session.
- `close-session` closes a session and signals a background command before dropping its channel.
- `read-session-output` reads output from background work such as `tail -f`.
- `read-command` runs allowlisted read-only commands including `ls`, `cat`, and `grep`.
- `run-command` runs arbitrary commands subject to approval rules.
- `privileged-command` runs commands with sudo.
- `sftp-upload`, `sftp-download`, and `sftp-list` handle content transfers and remote directory listing.
- `sftp-upload-file` and `sftp-download-file` stream files between disk and the remote host without passing file contents through model context.
- `signal-process` sends INT, TERM, or KILL to a remote process ID.
- `reload-config` reports configuration status or reloads the file.

The regular SFTP upload replaces its destination unconditionally. The file-streaming upload instead requires an explicit overwrite option before replacing an existing destination.

## Limitations and notes

SSH access still exposes private data, untrusted input, and network egress to agent-driven operations; approval and audit controls reduce exposure but do not eliminate that risk. Destructive or privileged actions need approval unless a profile sets `approvalPolicy = "auto"`. Configuration and credentials must be protected because they determine which hosts and policies the server can use.

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