# ssh-client-mcp-server [Health: Active]

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

## Description
MCP server for executing shell commands on remote hosts via SSH.

## Tools
Capabilities this server exposes over MCP:

- **exec** — Execute a shell command on the remote SSH server and return stdout.
- **soma_health** — Server uptime, status, active session count.
- **soma_capabilities** — Enumerate registered tools, resources, and prompts.
- **soma_connections** — Gateway connection status (unused here).

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

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

## Documentation

## What ssh-client-mcp-server does

ssh-client-mcp-server MCP server lets an MCP client execute shell commands on one configured remote host through SSH. The primary `exec` tool returns standard output from the remote command, while standard error is reported as a structured error. The package runs locally on Linux, macOS, or Windows wherever Node.js 22 or later is available.

The server is designed for a single SSH target. Its companion monorepo package, `ssh-fleet-mcp-server`, handles multi-host configurations, but that is a separate package and is not part of this connector’s single-host behavior.

## How it works

An MCP client launches the process and passes the SSH target and authentication settings as command-line arguments. The server establishes access to the configured host and exposes the remote command interface over the stdio MCP transport. The `--user` option is optional; without it, the local operating-system username is used. The default SSH port is 22.

In addition to remote execution, the server registers introspection endpoints supplied by its underlying framework. `soma_health` reports uptime, status, and active sessions. `soma_capabilities` lists registered tools, resources, and prompts. `soma_connections` reports gateway connection status, although that capability is unused for this connector.

For processes that need to continue between calls, tmux-backed tools can list sessions, send input, read recent pane output, and send control keys. A session is created when needed, and the default session name is `agent` unless changed with the tmux-session option. The remote machine must have tmux installed.

## Setup and configuration

The usual setup is to configure an MCP client to run the published package with `npx`; a global installation or a source build is also supported. The required connection argument is `--host`. Authentication can be supplied with `--password`, a private-key path using `--key`, a PEM value named by `--key-env`, or the local SSH agent through `--agent=true`.

Authentication options are considered in this order: password, key path, key environment variable, then agent. The key path accepts `~`, shell-style environment-variable forms, and relative paths. The server validates a configured key during startup, so invalid key material can fail before the first command is executed. If no authentication option is supplied, startup can still complete, but SSH authentication will fail when `exec` is called.

For agent-based authentication, `SSH_AUTH_SOCK` must point to a reachable SSH-agent socket. This can include agents exposed by supported desktop password managers. Keep passwords and private keys out of checked-in client configuration files.

## Tools and capabilities

- `exec`: Run a shell command on the configured remote host and return its output.
- `tmux_list`: List live remote tmux sessions.
- `tmux_send`: Send text to a tmux session and optionally submit it.
- `tmux_read`: Read a recent pane transcript, up to 2,000 lines.
- `tmux_keys`: Send control or special keys such as `C-c`.
- `soma_health`, `soma_capabilities`, and `soma_connections`: Expose server status, registered MCP capabilities, and connection status.

## Limitations and notes

ssh-client-mcp-server MCP server targets one configured SSH host rather than a fleet. Remote command behavior depends on the target shell, account permissions, network reachability, and SSH authentication setup. Tmux features require tmux on the remote host, and full-screen terminal interfaces may not produce clean transcripts; line-oriented programs are better suited to `tmux_read`.

The package is provided under the MIT License and is not affiliated with or endorsed by an SSH vendor.

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