# blakerouse/ssh-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/blakerouse/ssh-mcp  
**GitHub Stars:** 20  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/blakerouse-ssh-mcp

## Description
MCP server exposing SSH control for Linux and Windows servers. Allows long running commands and the ability to perform commands on multiple hosts at the same time.

## Tools
Capabilities this server exposes over MCP:

- **add_host** — Adds a new Linux or Windows host to the SSH configuration with automatic OS detection. Username and password are optional in the connection string - if not provided, the current user and SSH agent will be used for authentication.
- **remove_host** — Removes a host from the SSH configuration by group and name.
- **get_groups** — Retrieves the list of all groups from the SSH configuration.
- **get_hosts** — Retrieves the list of hosts from the SSH configuration. Can optionally filter by group.
- **get_os_info** — Retrieves the cached operating system information for Linux and Windows hosts. You can specify individual hosts or an entire group.
- **update_os_info** — Updates the cached operating system information for Linux and Windows hosts. You can specify individual hosts or an entire group.
- **perform_command** — SSH into a remote machine and executes a command. You can specify individual hosts or an entire group. Commands that take longer than 30 seconds are automatically moved to background execution. Use background=true to run immediately in background.
- **get_command_status** — Retrieves the status and results of a background command by its command ID. If no ID is provided, returns the most recent command.
- **list_commands** — Lists all background commands with their current status. Useful for tracking long-running commands.
- **cancel_command** — Cancels a running background command by its command ID.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

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

## Documentation

## What blakerouse/ssh-mcp MCP server does

The blakerouse/ssh-mcp MCP server gives an MCP client tools for maintaining an SSH host inventory and operating those hosts remotely. Hosts can be added to named groups, listed by group, removed, and inspected for cached operating-system information. Remote systems may run Linux or Windows; the server detects the operating system when a host is added and can refresh that information later.

The main execution tool runs a command on selected hosts or on every host in a group. This supports tasks such as checking uptime, inspecting disk space, or running service commands across a group. Results from commands that finish promptly are returned directly.

## How it works

The process runs locally and connects to configured remote machines through SSH. Host records are organized by group, with hosts addressable individually or through their group. The server uses local persistent storage backed by BadgerDB for this configuration and command state.

Commands that exceed 30 seconds are moved into background execution. A background command receives an identifier that can be used to retrieve its status and results. The command-management tools also list active or completed background jobs and cancel a running job by ID. Passing a background option starts a command asynchronously without waiting for the initial 30-second interval.

The blakerouse/ssh-mcp MCP server supports password authentication, SSH agent authentication, and SSH key files such as the usual files under `~/.ssh`. SSH agent support is Unix-only, while password and key-file authentication work across the supported platforms. Host verification uses `~/.ssh/known_hosts`, with automatic host addition described in the project documentation.

## Setup and configuration

Build the server from its GitHub repository with Go:

```sh
git clone https://github.com/blakerouse/ssh-mcp
go build .
```

Configure an MCP client to launch the resulting binary as a local server. The README provides a Claude Desktop `mcpServers` entry whose `command` points to the built binary, then instructs users to restart Claude Desktop. The exact binary path depends on where the project is checked out and built, so it must be supplied in the client configuration by the operator.

Hosts are added through connection strings. Usernames and passwords may be included, or the connection can rely on the current user and SSH agent when those values are omitted. The server accepts connection strings with or without an `ssh://` prefix and supports specifying a non-default port.

## Tools and capabilities

The blakerouse/ssh-mcp MCP server exposes these tool groups:

- Host administration: `add_host`, `remove_host`, `get_groups`, and `get_hosts`.
- Operating-system data: `get_os_info` for cached details and `update_os_info` to refresh them.
- Remote execution: `perform_command` for one or more hosts, with immediate or background execution.
- Background-job control: `get_command_status`, `list_commands`, and `cancel_command`.

## Limitations and notes

SSH agent access depends on the Unix `SSH_AUTH_SOCK` mechanism and is not available on Windows. Remote hosts are limited to Linux and Windows systems with SSH access. Commands run across multiple hosts concurrently, so an operation targeting a group can produce results from several machines and may create a background job when it runs beyond the synchronous timeout.

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