Installation

Installation

ssh-mcp can be installed three ways: as a local binary registered into an AI client, as a Docker container, or as a one-click MCPB bundle. All three produce the same result: an MCP server entry in your client's config file.

Prerequisites

• One or more SSH-reachable remote servers.
• An MCP-compatible AI client: Claude Desktop, Claude Code, Cursor, Devin, VS Code, or Cline.
• For local binary install: Go 1.26+ to build, or a prebuilt binary from the Releases page.
• For Docker install: Docker or Docker Desktop.

Option A: local binary

1. Build the binary

git clone https://github.com/overklassniy/ssh-mcp.git
cd ssh-mcp
make build

This produces an ssh-mcp executable in the repo root. Alternatively, download a prebuilt binary for your platform from the Releases page and put it on your PATH.

2. Create a config file

See Configuration for the full reference. A minimal config:

[[server]]
name = "web"
host = "example.com"
username = "deploy"
port = 22
private_key = "~/.ssh/id_ed25519"

Save it as ssh-mcp.toml.

3. Register in your client

ssh-mcp install --client claude-code --config ./ssh-mcp.toml

Replace claude-code with one of:

Client	Value
Claude Desktop	claude-desktop
Claude Code	claude-code
Cursor	cursor
Devin	Devin
VS Code	vscode
Cline	cline

Use --dry-run first to preview the entry without writing it:

ssh-mcp install --client claude-code --config ./ssh-mcp.toml --dry-run

The install command merges non-destructively into your client's existing config file, creates a .bak backup before overwriting, and creates parent directories as needed. It never removes other server entries.

4. Restart your client

MCP clients read their config at startup. Restart Claude Desktop (or your chosen client) so it picks up the new entry.

Option B: Docker

Docker mode registers a docker run -i --rm entry instead of a direct executable. The host home directory is bind-mounted at the same path so ~/ references in the TOML resolve identically inside the container, the SSH agent socket is forwarded when SSH_AUTH_SOCK is set, and sensitive values are passed via -e from the host environment.

ssh-mcp install --client claude-code --docker --config ./ssh-mcp.toml

The image defaults to ghcr.io/overklassniy/ssh-mcp:latest. Override it with --docker-image:

ssh-mcp install --client claude-code --docker \
  --docker-image ghcr.io/overklassniy/ssh-mcp:dev \
  --config ./ssh-mcp.toml

Platform notes for Docker mode

Docker install mode is best supported on Linux, where bind mounts and unix sockets map directly. On macOS and Windows (Docker Desktop), host paths are translated through a VM layer and absolute paths differ; some manual -v adjustment may be needed. SSH agent forwarding via a unix socket works on Linux and macOS but not on Windows (named pipes are not forwarded by Docker Desktop).

Local file upload/download paths outside the home directory require extra -v mounts in the generated entry, because the container filesystem is otherwise isolated.

Option C: MCPB one-click bundle

MCPB (MCP Bundle) is the cross-client standard for one-click installation of local MCP servers. It is supported by Claude Desktop, Claude Code, and MCP for Windows.

1. Download the .mcpb bundle for your platform from the Releases page.
2. Open the bundle in your client. The client prompts for SSH connection details (host, port, username, password or private key, passphrase, 2FA toggle) on first install.
3. Sensitive values (password, passphrase) are passed via environment variables, not CLI args.

Cursor, Devin, and VS Code users should use Option A or B instead, as those clients do not currently support MCPB one-click install.

Building bundles from source

make mcpb

This builds per-platform bundles into dist/, each containing manifest.json and the binary under server/. Requires zip on PATH.

Single-server mode (no config file)

For quick one-off use, you can skip the TOML file and pass connection details as CLI flags. The binary builds a single-server config from the flags:

ssh-mcp --host example.com --username deploy --port 22 \
  --private-key ~/.ssh/id_ed25519

In this mode, --ssh-config can resolve a host alias from ~/.ssh/config:

ssh-mcp --host myalias --ssh-config ~/.ssh/config

Alias resolution only runs when the host is not an IP address and does not contain a dot, and only when --ssh-config is provided.

Verifying the install

After installing and restarting your client, ask the agent to list the configured servers:

Use the list-servers tool.

You should see your server with a connected or disconnected status. Then try a simple command:

Run uname -a on the web server using execute-command.

If something goes wrong, see Troubleshooting.