Ssh MCP

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:

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.