ssh-mcp-pro

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

Install globally with pnpm:

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

Run without a global install:

npx ssh-mcp-pro

For pnpm-only environments, use:

pnpm dlx ssh-mcp-pro

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

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:

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

VS Code settings style:

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

Claude Desktop style:

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

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

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:

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.

| Variable | Default | Purpose | | --- | --- | --- | | SSH_MCP_MAX_SESSIONS | 20 | Maximum concurrent SSH sessions. | | SSH_MCP_SESSION_TTL | 900000 | Session time-to-live in milliseconds. | | SSH_MCP_COMMAND_TIMEOUT | 30000 | Default remote command timeout in milliseconds. | | SSH_MCP_MAX_COMMAND_OUTPUT_BYTES | 1048576 | Maximum buffered stdout/stderr bytes per command result. | | SSH_MCP_MAX_STREAM_CHUNKS | 4096 | Maximum retained streaming chunks. | | SSH_MCP_MAX_FILE_SIZE | 10485760 | Maximum bytes returned by text-focused file reads. | | SSH_MCP_MAX_FILE_WRITE_BYTES | 10485760 | Maximum accepted write payload before buffering. | | SSH_MCP_MAX_TRANSFER_BYTES | 52428800 | Maximum upload or download transfer size. | | SSH_MCP_DEBUG | false | Enables debug-oriented configuration behavior. | | SSH_MCP_RATE_LIMIT | true | Enables the global MCP request rate limiter. | | SSH_MCP_RATE_LIMIT_MAX | 100 | Maximum requests per rate-limit window. | | SSH_MCP_RATE_LIMIT_PER_SESSION | true | Enables per-session MCP request rate limiting when tool arguments include sessionId. | | SSH_MCP_RATE_LIMIT_PER_SESSION_MAX | 50 | Maximum requests per SSH session per rate-limit window. | | SSH_MCP_RATE_LIMIT_PER_SESSION_WINDOW_MS | 60000 | Per-session rate-limit window in milliseconds. | | SSH_MCP_RATE_LIMIT_WINDOW_MS | 60000 | Rate-limit window in milliseconds. | | SSH_MCP_STRICT_HOST_KEY | unset | Legacy boolean alias for strict vs insecure host-key checking. | | SSH_MCP_HOST_KEY_POLICY | strict | Host-key mode: strict, accept-new, or insecure. | | SSH_MCP_KNOWN_HOSTS_PATH | ~/.ssh/known_hosts | Known hosts file used for strict host-key verification. | | SSH_MCP_ALLOW_ROOT_LOGIN | false | Allows SSH login as root and mirrors into policy. | | SSH_MCP_ALLOWED_CIPHERS | empty | Optional SSH cipher allowlist. | | SSH_MCP_POLICY_FILE | unset | JSON file containing partial policy overrides. | | SSH_MCP_POLICY_MODE | enforce | Policy decision mode: enforce or explain. | | SSH_MCP_ALLOW_RAW_SUDO | false | Allows raw proc_sudo; prefer ensure_* tools. | | SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS | false | Allows commands matching destructive command policy. | | SSH_MCP_ALLOW_DESTRUCTIVE_FS | false | Allows destructive filesystem operations such as fs_rmrf. | | SSH_MCP_ALLOWED_HOSTS | empty | Host allowlist for policy and remote connector safety checks. | | SSH_MCP_COMMAND_ALLOW | empty | Command allow patterns. | | SSH_MCP_COMMAND_DENY | empty | Command deny patterns. | | SSH_MCP_PATH_ALLOW_PREFIXES | /tmp,/var/tmp,/home,/Users | Remote path prefixes allowed by filesystem policy. | | SSH_MCP_PATH_DENY_PREFIXES | /etc/sudoers,/etc/shadow,/etc/passwd,/boot,/dev,/proc | Remote path prefixes denied by filesystem policy. | | SSH_MCP_LOCAL_PATH_ALLOW_PREFIXES | OS temp directory | Local paths allowed for transfer operations. | | SSH_MCP_LOCAL_PATH_DENY_PREFIXES | empty | Local paths denied for transfer operations. | | SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS | 127.0.0.1,localhost,::1 | Local bind hosts allowed for tunnels. | | SSH_MCP_TUNNEL_DENY_BIND_HOSTS | 0.0.0.0,:: | Local bind hosts denied for tunnels. | | SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTS | empty | Optional remote tunnel target host allowlist. | | SSH_MCP_TUNNEL_DENY_REMOTE_HOSTS | empty | Optional remote tunnel target host denylist. | | SSH_MCP_TUNNEL_ALLOW_PORTS | empty | Optional tunnel port allowlist. | | SSH_MCP_TUNNEL_DENY_PORTS | empty | Optional tunnel port denylist. | | SSH_MCP_HTTP_HOST | 127.0.0.1 | Streamable HTTP bind host. | | SSH_MCP_HTTP_PORT | 3000 | Streamable HTTP bind port. | | SSH_MCP_HTTP_ALLOWED_ORIGINS | http://127.0.0.1,http://localhost | Browser origins allowed for HTTP clients. | | SSH_MCP_HTTP_BEARER_TOKEN_FILE | unset | Bearer token file for HTTP transport. Required for non-loopback bearer deployments. | | SSH_MCP_ENABLE_LEGACY_SSE | false | Enables legacy SSE compatibility. | | SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES | 1048576 | Maximum HTTP request body size. | | SSH_MCP_HTTP_MAX_SESSIONS | 20 | Maximum HTTP MCP sessions. | | SSH_MCP_HTTP_SESSION_IDLE_TTL_MS | 900000 | HTTP MCP session idle timeout in milliseconds. | | SSH_MCP_HTTP_PUBLIC_URL | unset | Stable public HTTPS MCP URL for protected resource metadata. | | SSH_MCP_HTTP_TRUST_PROXY | false | Trust reverse proxy forwarded headers. | | SSH_MCP_TOOL_PROFILE | full | Active tool exposure profile. | | SSH_MCP_CONNECTOR_PROFILE | full | Alias for SSH_MCP_TOOL_PROFILE. | | SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER | none | Credential provider: none, agent, or command. | | SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND | unset | External credential command when provider is command. | | SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGS | empty | Arguments passed to the external credential command. | | SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS | 5000 | Credential command timeout in milliseconds. | | SSH_MCP_CONNECTOR_DEFAULT_USERNAME | unset | Default username for connector broker flows. | | SSH_MCP_HTTP_AUTH_MODE | bearer | HTTP auth mode: bearer or oauth. | | SSH_MCP_OAUTH_ISSUER | unset | Expected OAuth issuer. | | SSH_MCP_OAUTH_AUDIENCE | unset | Expected OAuth audience. | | SSH_MCP_OAUTH_JWKS_URL | unset | OAuth JWKS URL. | | SSH_MCP_OAUTH_RESOURCE | unset | OAuth protected resource identifier. | | SSH_MCP_OAUTH_REQUIRED_SCOPES | ssh-mcp-pro.read | Required OAuth scopes. |

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.

| Profile | Exposed tools | Exposed resources | Exposed prompts | | --- | --- | --- | --- | | full | All SSH, process, filesystem, transfer, ensure, tunnel, connector, and system tools. | All runtime resources. | All prompts. | | remote-safe | connector_status, ssh_hosts_list, ssh_policy_explain, ssh_host_inspect, ssh_mutation_plan. | ssh-mcp-pro://capabilities/support-matrix. | inspect-host-capabilities, plan-mutation. | | chatgpt | Baseline remote connector tools plus an empty ChatGPT extension set. | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. | | claude | Baseline remote connector tools plus an empty Claude extension set. | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. | | remote-readonly | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. | | remote-broker | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. | Same remote connector subset as remote-safe. |

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

• INSTALL.md covers full client setup and troubleshooting.
• API reference is generated from the published TypeScript entry points.
• CHANGELOG.md records release history in Keep a Changelog format.
• AGENTS.md describes agent-facing operational guidance.
• examples/README.md contains workflow examples.
• ARCHITECTURE.md explains the major subsystems and ADRs.
• REGISTRY_SUBMISSION.md tracks MCP Registry submission readiness.

Contributing

See CONTRIBUTING.md for setup, quality gates, commit rules, and pull request expectations.

License

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