ssh-mcp-pro

io.github.oaslanankaPublished by GitHub account oaslanankav1.4.0Updated Nov 7, 2026

Secure MCP SSH automation server with policy controls, resources, prompts, stdio, and HTTP.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Policy-controlled SSH automation server that lets an assistant open SSH sessions, inspect hosts, run guarded commands, manage files and services, and plan…

What you can do
  • Discover and inspect hosts: list configured SSH hosts, resolve aliases, explain policy decisions, inspect a host read-only, and draft non-executing mutation plans
  • Manage SSH sessions: open, close, list and ping sessions, with host-key policy settings
  • Run remote commands: execute non-interactive or streaming commands, list and kill processes, and run sudo only when policy allows
  • Work with remote files: read, write, stat, list, create directories, rename, remove, apply patches, and ensure lines in files
  • Operate services and packages: list, inspect, start, stop and restart systemd services, read journal logs, and ensure packages are installed or removed
  • Check system state: OS detection, disk…
When to use it
Useful when an assistant needs to operate Linux or Unix hosts over SSH from a chat client: read-only host inspection, guarded command execution, routine file and service maintenance, or drafting a change plan before applying it. The remote-safe profiles suit connector setups where only inspection and planning should be exposed.
Requirements
Runs as a local Node.js process (Node.js 22.22.2+, 24.15.0+ or 26.3.0+; pnpm 11.0.9+ for global install) via npx or a global install, or as a published container image. Needs SSH access and credentials for the target hosts, plus a known_hosts file for strict host-key checks. Optional HTTP transport needs SSH_MCP_HTTP_BEARER_TOKEN_FILE, SSH_MCP_HTTP_PUBLIC_URL, allowed origins and, for OAuth, issuer, audience and JWKS settings.
Before you install
The full tool profile can write, delete, restart services, kill processes and run sudo on remote hosts; destructive commands and filesystem operations are blocked by default but can be enabled through policy variables such as SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS, SSH_MCP_ALLOW_DESTRUCTIVE_FS and SSH_MCP_ALLOW_RAW_SUDO. Host-key checking defaults to strict; the insecure mode weakens verification. Exposing the HTTP transport beyond loopback requires a bearer token file and a restricted tool…

Installation

In SourceWeft

  1. Open ssh-mcp-pro in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ssh-mcp-pro

Policy-controlled SSH automation for MCP clients

[npm version] [npm downloads] [license] [CI] [API Docs]

[GitGem]   ·   Explore source on DeepWiki

[Buy me a coffee]

ssh-mcp-pro is a secure Model Context Protocol (MCP) server for SSH automation. It lets MCP-capable clients open SSH sessions, inspect hosts, run guarded commands, manage files, transfer artifacts, create tunnels, and perform idempotent package or service work through policy-controlled tools.

Prerequisites

  • Node.js >=22.22.2 or >=24.15.0 or >=26.3.0
  • pnpm >=11.0.9
  • SSH access to the target hosts
  • Docker, only for local integration tests and container image builds

Installation

For Windows/Linux outbound agent connection status, rotating diagnostics and a live PowerShell log view, see Agent Activity Monitor.

Install globally with pnpm:

bash
pnpm add --global ssh-mcp-prossh-mcp-pro --version

Run without a global install:

bash
npx ssh-mcp-pro

For pnpm-only environments, use:

bash
pnpm dlx ssh-mcp-pro

Container images are published to GitHub Container Registry for release tags:

bash
docker run --rm ghcr.io/oaslananka/ssh-mcp-pro:1.0.0 --version

Images are published for linux/amd64 and linux/arm64 with exact semver and Git tag aliases. Production deployments should prefer the digest-pinned reference recorded by the release workflow. See Docker Usage for the tag policy, digest-pinned examples, and registry verification steps.

Quickstart

Generic stdio MCP config:

json
{  "name": "ssh-mcp-pro",  "command": "ssh-mcp-pro",  "type": "stdio"}

VS Code workspace .vscode/mcp.json configuration:

json
{  "servers": {    "ssh-mcp-pro": {      "type": "stdio",      "command": "ssh-mcp-pro",      "args": []    }  }}

Claude Desktop style:

json
{  "mcpServers": {    "ssh-mcp-pro": {      "command": "ssh-mcp-pro",      "args": []    }  }}

After registration, start with discovery and a strict host-key policy:

text
List configured SSH hosts, open a session to bastion.example.com as deploy with hostKeyPolicy=strict, then run os_detect.

Usage

Use ssh-mcp-pro from an MCP client over stdio, or run the HTTP transport for remote-safe connector profiles. Start with read-only discovery tools, inspect the active policy, and create explicit sessions before running remote commands:

text
List configured SSH hosts, explain the active SSH policy, connect to the selected host, then report its operating system and disk usage.

See examples/README.md for additional workflows and INSTALL.md for client-specific setup.

Configuration

All SSH_MCP_* environment variables parsed by src/config.ts are listed below. Comma-separated settings also accept newline-separated values.

VariableDefaultPurpose
SSH_MCP_MAX_SESSIONS20Maximum concurrent SSH sessions.
SSH_MCP_SESSION_TTL900000Session time-to-live in milliseconds.
SSH_MCP_COMMAND_TIMEOUT30000Default remote command timeout in milliseconds.
SSH_MCP_MAX_COMMAND_OUTPUT_BYTES1048576Maximum buffered stdout/stderr bytes per command result.
SSH_MCP_MAX_STREAM_CHUNKS4096Maximum retained streaming chunks.
SSH_MCP_MAX_FILE_SIZE10485760Maximum bytes returned by text-focused file reads.
SSH_MCP_MAX_FILE_WRITE_BYTES10485760Maximum accepted write payload before buffering.
SSH_MCP_MAX_TRANSFER_BYTES52428800Maximum upload or download transfer size.
SSH_MCP_DEBUGfalseEnables debug-oriented configuration behavior.
SSH_MCP_RATE_LIMITtrueEnables the global MCP request rate limiter.
SSH_MCP_RATE_LIMIT_MAX100Maximum requests per rate-limit window.
SSH_MCP_RATE_LIMIT_PER_SESSIONtrueEnables per-session MCP request rate limiting when tool arguments include sessionId.
SSH_MCP_RATE_LIMIT_PER_SESSION_MAX50Maximum requests per SSH session per rate-limit window.
SSH_MCP_RATE_LIMIT_PER_SESSION_WINDOW_MS60000Per-session rate-limit window in milliseconds.
SSH_MCP_RATE_LIMIT_WINDOW_MS60000Rate-limit window in milliseconds.
SSH_MCP_STRICT_HOST_KEYunsetLegacy boolean alias for strict vs insecure host-key checking.
SSH_MCP_HOST_KEY_POLICYstrictHost-key mode: strict, accept-new, or insecure.
SSH_MCP_KNOWN_HOSTS_PATH~/.ssh/known_hostsKnown hosts file used for strict host-key verification.
SSH_MCP_ALLOW_ROOT_LOGINfalseAllows SSH login as root and mirrors into policy.
SSH_MCP_ALLOWED_CIPHERSemptyOptional SSH cipher allowlist.
SSH_MCP_POLICY_FILEunsetJSON file containing partial policy overrides.
SSH_MCP_POLICY_MODEenforcePolicy decision mode: enforce or explain.
SSH_MCP_ALLOW_RAW_SUDOfalseAllows raw proc_sudo; prefer ensure_* tools.
SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDSfalseAllows commands matching destructive command policy.
SSH_MCP_ALLOW_DESTRUCTIVE_FSfalseAllows destructive filesystem operations such as fs_rmrf.
SSH_MCP_ALLOWED_HOSTSemptyHost allowlist for policy and remote connector safety checks.
SSH_MCP_COMMAND_ALLOWemptyCommand allow patterns.
SSH_MCP_COMMAND_DENYemptyCommand deny patterns.
SSH_MCP_PATH_ALLOW_PREFIXES/tmp,/var/tmp,/home,/UsersRemote path prefixes allowed by filesystem policy.
SSH_MCP_PATH_DENY_PREFIXES/etc/sudoers,/etc/shadow,/etc/passwd,/boot,/dev,/procRemote path prefixes denied by filesystem policy.
SSH_MCP_LOCAL_PATH_ALLOW_PREFIXESOS temp directoryLocal paths allowed for transfer operations.
SSH_MCP_LOCAL_PATH_DENY_PREFIXESemptyLocal paths denied for transfer operations.
SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS127.0.0.1,localhost,::1Local bind hosts allowed for tunnels.
SSH_MCP_TUNNEL_DENY_BIND_HOSTS0.0.0.0,::Local bind hosts denied for tunnels.
SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTSemptyOptional remote tunnel target host allowlist.
SSH_MCP_TUNNEL_DENY_REMOTE_HOSTSemptyOptional remote tunnel target host denylist.
SSH_MCP_TUNNEL_ALLOW_PORTSemptyOptional tunnel port allowlist.
SSH_MCP_TUNNEL_DENY_PORTSemptyOptional tunnel port denylist.
SSH_MCP_HTTP_HOST127.0.0.1Streamable HTTP bind host.
SSH_MCP_HTTP_PORT3000Streamable HTTP bind port.
SSH_MCP_HTTP_ALLOWED_ORIGINShttp://127.0.0.1,http://localhostBrowser origins allowed for HTTP clients.
SSH_MCP_HTTP_BEARER_TOKEN_FILEunsetBearer token file for HTTP transport. Required for non-loopback bearer deployments.
SSH_MCP_ENABLE_LEGACY_SSEfalseEnables legacy SSE compatibility.
SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES1048576Maximum HTTP request body size.
SSH_MCP_HTTP_MAX_SESSIONS20Maximum active Streamable HTTP MCP sessions. Expired sessions are cleaned first; if capacity is still full, the oldest idle session is evicted so abandoned clients do not cause persistent 502s. Use 100 for ChatGPT/Cloudflare production deployments.
SSH_MCP_HTTP_SESSION_IDLE_TTL_MS900000HTTP MCP session idle timeout in milliseconds. Use 300000 for ChatGPT/Cloudflare production deployments where clients may abandon sessions without DELETE.
SSH_MCP_HTTP_PUBLIC_URLunsetStable public HTTPS MCP URL for protected resource metadata.
SSH_MCP_HTTP_TRUST_PROXYfalseTrust reverse proxy forwarded headers.
SSH_MCP_TOOL_PROFILEfullActive tool exposure profile.
SSH_MCP_CONNECTOR_PROFILEfullAlias for SSH_MCP_TOOL_PROFILE.
SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDERnoneCredential provider: none, agent, or command.
SSH_MCP_CONNECTOR_CREDENTIAL_COMMANDunsetExternal credential command when provider is command.
SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGSemptyArguments passed to the external credential command.
SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS5000Credential command timeout in milliseconds.
SSH_MCP_CONNECTOR_DEFAULT_USERNAMEunsetDefault username for connector broker flows.
SSH_MCP_HTTP_AUTH_MODEbearerHTTP auth mode: bearer or oauth.
SSH_MCP_OAUTH_ISSUERunsetExpected OAuth issuer.
SSH_MCP_OAUTH_AUDIENCEunsetExpected OAuth audience.
SSH_MCP_OAUTH_JWKS_URLunsetOAuth JWKS URL.
SSH_MCP_OAUTH_RESOURCEunsetOAuth protected resource identifier.
SSH_MCP_OAUTH_REQUIRED_SCOPESssh-mcp-pro.readRequired OAuth scopes.
SSH_MCP_OAUTH_ALLOWED_ALGORITHMSunsetOptional comma-separated JWT algorithm allowlist, for example RS256,ES256. When unset, the built-in OAuth verifier defaults are used.
SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGHunsetWhen enabled with 1, true, yes, or on, lets /mcp requests bypass the remote control plane and reach the Streamable HTTP MCP handler. Use only for connector routing migrations.

The parser also accepts non-SSH_MCP_* compatibility aliases PORT, KNOWN_HOSTS_PATH, and STRICT_HOST_KEY_CHECKING.

Tool Profiles

full exposes every registered tool, resource, and prompt. Every other profile uses an explicit per-profile allowset. chatgpt and claude currently expose the same baseline connector tools as remote-safe, with empty client-specific extension sets reserved for future additions.

ProfileExposed toolsExposed resourcesExposed prompts
fullAll SSH, process, filesystem, transfer, ensure, tunnel, connector, and system tools.All runtime resources.All prompts.
remote-safeconnector_status, ssh_hosts_list, ssh_policy_explain, ssh_host_inspect, ssh_mutation_plan.ssh-mcp-pro://capabilities/support-matrix.inspect-host-capabilities, plan-mutation.
chatgptBaseline remote connector tools plus an empty ChatGPT extension set.Same remote connector subset as remote-safe.Same remote connector subset as remote-safe.
claudeBaseline remote connector tools plus an empty Claude extension set.Same remote connector subset as remote-safe.Same remote connector subset as remote-safe.
remote-readonlySame remote connector subset as remote-safe.Same remote connector subset as remote-safe.Same remote connector subset as remote-safe.
remote-brokerSame remote connector subset as remote-safe.Same remote connector subset as remote-safe.Same remote connector subset as remote-safe.

SSH_MCP_CHATGPT_EXTRA_TOOLS and SSH_MCP_CLAUDE_EXTRA_TOOLS can extend their profiles for loopback-only development. Non-loopback HTTP startup validates the fully resolved tool set against the canonical remote-safe allowlist and refuses unknown, session, transfer, filesystem mutation, process, sudo, service mutation, or tunnel tools. The startup error lists only the rejected tool names. Adding an extension locally does not make that tool approved for public connector exposure.

Security Defaults

ssh-mcp-pro starts with strict SSH host-key verification, denies root login, denies raw sudo, blocks destructive commands and filesystem operations unless policy allows them, and refuses non-loopback HTTP startup unless authentication, origins, public HTTPS URL, strict host-key verification, a remote-safe tool profile, and host allowlists are configured. See SECURITY.md for vulnerability reporting and SECURITY_DECISIONS.md for the design rationale behind these defaults.

More Documentation

Project Health & Governance

Contributing

See CONTRIBUTING.md for setup, quality gates, commit rules, and pull request expectations. Participation is governed by the Code of Conduct.

License

ssh-mcp-pro is available under the MIT License.

Agent plugin and runtime configuration

This repository owns the product-level agent plugin, MCP runtime configuration, and product-specific skills for ssh-mcp-pro. The central agent-tools repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server package.

FilePurpose
.claude-plugin/plugin.jsonClaude Code-valid product plugin manifest.
.mcp.jsonClaude Code project-local MCP server configuration.
.codex/config.example.tomlCodex CLI MCP configuration example.
.vscode/mcp.example.jsonVS Code / GitHub Copilot workspace MCP configuration example.
opencode.example.jsoncOpenCode project MCP configuration example.
.opencode/skills/OpenCode-native mirrored skill definitions.
docs/agent-runtime-config.mdAgent runtime setup and validation notes.

Validate plugin packaging locally:

bash
claude plugin validate .

Source: README.md at commit 99ae1c3

Tools

46

connector_status

Connector Status

Use this when ChatGPT or Claude needs to understand the remote connector profile, authentication mode, and credential broker readiness without exposing secrets.

Takes no parameters.

ssh_hosts_list

List Safe SSH Host Aliases

Use this when ChatGPT or Claude needs a safe list of SSH host aliases that may be inspected through the remote connector. Sensitive login material is omitted.

Takes no parameters.

ssh_policy_explain

Explain SSH Policy

Use this when ChatGPT or Claude needs to explain whether a requested SSH inspection or mutation would be allowed. This is explain-only and does not execute commands or open tunnels.

ParameterspathactioncommandhostAlias

ssh_host_inspect

Inspect SSH Host

Use this when ChatGPT or Claude needs read-only host inspection through the server-side credential broker. The user supplies only a configured host alias and selected checks; no secret material or login details are accepted.

ParameterscheckshostAliasrequired

ssh_mutation_plan

Plan SSH Mutation

Use this when ChatGPT or Claude needs a non-executing plan for a remote SSH change. It never runs commands, writes files, uploads data, starts tunnels, or escalates privileges.

ParametersgoalrequiredcategoryhostAliasrequired

ssh_open_session

Open SSH Session

Opens a new SSH session with authentication

ParametersauthhostrequiredportttlMspassworduseAgentusernamerequiredpassphrasepolicyModeprivateKeyhostKeyPolicyknownHostsPath+4 more

ssh_close_session

Close SSH Session

Closes an SSH session

ParameterssessionIdrequired

ssh_list_sessions

List SSH Sessions

Lists all active SSH sessions with their details

Takes no parameters.

ssh_ping

Ping SSH Session

Checks if an SSH session is still alive and responsive

ParameterssessionIdrequired

ssh_list_configured_hosts

List Configured Hosts

Lists all hosts configured in ~/.ssh/config

Takes no parameters.

ssh_resolve_host

Resolve SSH Host

Resolves a host alias from ~/.ssh/config to connection parameters

ParametershostAliasrequired

proc_exec

Execute Remote Command

Executes a non-interactive command on the remote system after policy and safety checks

ParameterscwdenvcommandrequiredsessionIdrequiredtimeoutMs

proc_sudo

Execute Sudo Command

Executes a command with sudo privileges only when allowRawSudo policy permits it

ParameterscwdcommandrequiredsessionIdrequiredtimeoutMs

proc_list

List Processes

Lists running processes on the remote system sorted by CPU usage

ParameterssessionIdrequired

proc_kill

Signal Process

Sends a signal to a running process by PID

ParameterspidrequiredsignalsessionIdrequired

proc_exec_stream

Execute Streaming Command

Executes a command and returns streaming output chunks

ParameterscwdenvcommandrequiredsessionIdrequiredtimeoutMs

fs_read

Read Remote File

Reads a file from the remote system

ParameterspathrequiredencodingmaxBytessessionIdrequired

fs_write

Write Remote File

Writes data to a file on the remote system

ParametersdatarequiredmodepathrequiredsessionIdrequired

fs_stat

Stat Remote Path

Gets file or directory statistics

ParameterspathrequiredsessionIdrequired

fs_list

List Remote Directory

Lists directory contents

ParameterspagepathrequiredlimitsessionIdrequired

fs_mkdirp

Create Remote Directories

Creates directories recursively

ParameterspathrequiredsessionIdrequired

fs_rmrf

Remove Remote Path Recursively

Removes files or directories recursively

ParameterspathrequiredsessionIdrequired

fs_rename

Rename Remote Path

Renames or moves a file/directory

ParameterstorequiredfromrequiredsessionIdrequired

ensure_package

Ensure Package State

Ensures a package is installed or removed

ParametersnamerequiredstatesessionIdrequired

ensure_service

Ensure Service State

Ensures a service is in the desired state

ParametersnamerequiredstaterequiredsessionIdrequired

ensure_lines_in_file

Ensure Lines In File

Ensures specific lines are present or absent in a file

ParameterspathrequiredlinesrequiredstatesessionIdrequiredcreateIfMissing

patch_apply

Apply Patch

Applies a patch to a file

ParametersdiffrequiredpathrequiredsessionIdrequired

os_detect

Detect Remote OS

Detects operating system and environment information

ParameterssessionIdrequired

get_metrics

Get Runtime Metrics

Returns server metrics including session counts, command statistics, and uptime

Parametersformat

service_list

List Services

Lists all systemd services and their current state

ParameterssessionIdrequired

service_status

Service Status

Gets the status of a systemd service

ParametersnamerequiredsessionIdrequired

service_logs

Service Logs

Reads recent journal logs for a systemd service

ParametersnamerequiredlinessessionIdrequired

service_restart

Restart Service

Restarts a systemd service

ParametersnamerequiredsessionIdrequired

service_stop

Stop Service

Stops a systemd service

ParametersnamerequiredsessionIdrequired

disk_usage

Disk Usage

Reports disk usage for filesystems on the remote system

ParameterspathsessionIdrequired

memory_info

Memory Info

Reports memory usage on the remote system

ParameterssessionIdrequired

cpu_usage

CPU Usage

Reports CPU load average and uptime on the remote system

ParameterssessionIdrequired

net_interfaces

Network Interfaces

Lists network interfaces and their IP addresses on the remote system

ParameterssessionIdrequired

port_check

Port Check

Checks which processes are listening on a specific port

ParametershostportrequiredsessionIdrequired

log_tail

Tail Log

Tails the end of a log file or reads recent journal entries for a service

ParameterspathlinesservicesessionIdrequired

file_upload

Upload File

Uploads a local file to the remote host over SFTP

ParameterslocalPathrequiredsessionIdrequiredremotePathrequired

file_download

Download File

Downloads a remote file to the local machine over SFTP

ParameterslocalPathrequiredsessionIdrequiredremotePathrequired

tunnel_local_forward

Create Local SSH Tunnel

Creates a local SSH port forward

ParameterslocalPortrequiredsessionIdrequiredremoteHostrequiredremotePortrequired

tunnel_remote_forward

Create Remote SSH Tunnel

Creates a remote SSH port forward

ParameterslocalHostrequiredlocalPortrequiredsessionIdrequiredremotePortrequired

tunnel_close

Close SSH Tunnel

Closes an active tunnel

ParameterstunnelIdrequired

tunnel_list

List SSH Tunnels

Lists active tunnels, optionally filtered by session

ParameterssessionId

Version history

3
  1. v1.4.0LatestNov 6, 2026
  2. v1.2.3Oct 9, 2026
  3. v1.1.5Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts