SSH Client MCP server

SSH Client MCP Server

SSH Client MCP Server is a local Model Context Protocol (MCP) server that lets LLMs and other MCP clients execute shell commands on remote hosts over SSH. It runs from Linux, macOS, or Windows and targets any reachable SSH server (Linux, macOS, Windows with OpenSSH, etc.).

Built on somamcp — a functional MCP framework over FastMCP with telemetry, introspection, and backend abstraction.

Contents

• Quick Start
• Features
• Tools
• Installation
• Configuration
• Client Setup
• Testing
• Development
• Disclaimer

Monorepo

This repository is a pnpm monorepo with three packages:

Run the full validation suite across all packages:

pnpm -r validate

Quick Start

1. Configure your MCP client (Claude Desktop, Cursor, Cline, etc.) to launch this server via npx — see Client Setup.
2. Ask your LLM to run shell commands on the target host.

No global install required — npx fetches and runs the latest published version.

Features

• Single exec tool — runs a shell command on the remote host, returns stdout. stderr surfaces as a structured error.
• Four auth modes — password, key file, key from environment variable (e.g. injected by envpkt, Vault, Doppler), or SSHAUTHSOCK (system ssh-agent, 1Password, Bitwarden Desktop, KeePassXC).
• Smart path expansion — --key supports ~, $VAR, ${VAR}, and relative paths via functype-os. Unresolved variables fail fast with a typed error.
• OS-user fallback — --user defaults to the current OS username when omitted.
• Fail-fast auth — the SSH key is loaded and validated at server startup, not on the first exec call.
• Introspection out-of-the-box — somahealth, somacapabilities, soma_connections auto-registered by somamcp.
• Cross-platform — runs on Linux, macOS, Windows (anywhere Node 22+ runs).

Tools

Persistent sessions (tmux)

For driving long-running interactive processes (e.g. a remote coding agent) across calls, the server exposes tmux-backed tools. tmux must be installed on the remote host.

Shortened. The full README is on GitHub.