ssh-mcp-pro

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:

pnpm add --global ssh-mcp-prossh-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 workspace .vscode/mcp.json configuration:

{  "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.

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.

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

• 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.
• docs/tutorials/getting-started.md, docs/how-to/, docs/reference/, and docs/explanation/ organize the docs above by task (tutorial, how-to, reference, explanation).
• docs/troubleshooting.md covers common failure modes.

Project Health & Governance

• GOVERNANCE.md describes how decisions are made today.
• MAINTAINERS.md lists current maintainers.
• ROADMAP.md tracks known process gaps and what's planned to close them.
• CODE_OF_CONDUCT.md sets community expectations.
• docs/repo-maturity-report.md is an evidence-based audit of this repository's open-source and OpenSSF maturity, including what's not yet in place.

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.

Validate plugin packaging locally:

claude plugin validate .