mcp-ssh-tool

Production-grade MCP SSH automation for operators, developers, and AI clients. mcp-ssh-tool opens persistent SSH sessions and exposes safe, structured tools for command execution, file operations, transfers, tunnels, package/service management, metrics, resources, and guided prompts.

v2 is secure by default: strict host-key verification is on, root login is off, raw sudo is policy-gated, destructive commands and filesystem mutations are denied unless policy allows them, and remote HTTP starts on loopback only unless bearer auth and allowed origins are configured.

Why This Server

• Trust: central policy engine, structured audit events, redacted logs, strict host keys, and machine-readable errors.

• MCP quality: stdio for local clients, Streamable HTTP for remote clients, legacy SSE only behind an explicit compatibility flag.

• AI-friendly tools: stable output schemas, structuredContent, annotations for read-only/destructive/idempotent behavior, resources, and curated prompts.

• Operations: session TTL/eviction, command timeouts, transfer checksum verification, real SSH forwarding, Prometheus metrics, and OpenTelemetry hooks.

• Portability: SFTP first, POSIX/BusyBox-aware shell fallbacks for basic file operations, and explicit support boundaries.

Quick Start

Run without installing:

npx -y mcp-ssh-tool --version

Or install globally:

npm install -g mcp-ssh-tool

Add a stdio MCP server to your client:

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

Use it from your MCP client:

Open a safe SSH session to prod-1 as deploy, inspect host capabilities, then show disk usage.

Requirements

• Node.js 22.22.2+ or 24.14.1+ (LTS only)

• SSH access to target hosts

• A populated known_hosts file for strict host verification, or an explicit per-session host-key policy

Transports

Non-loopback HTTP startup is refused unless both --bearer-token-file and allowed origins are configured.

Secure Defaults

Per-session policyMode: "explain" returns a plan/verdict without executing. Use it before mutations when an AI client needs to summarize risk.

Policy Example

Set SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json:

{
  "mode": "enforce",
  "allowRootLogin": false,
  "allowRawSudo": false,
  "allowDestructiveCommands": false,
  "allowDestructiveFs": false,
  "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
  "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
  "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
  "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
  "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}

Simple deploys can use environment overrides such as SSH_MCP_ALLOW_RAW_SUDO=true, SSH_MCP_ALLOWED_HOSTS=prod-1.example.com, or SSH_MCP_PATH_ALLOW_PREFIXES=/tmp,/home/deploy.

Core Tools

• ssh_open_session, ssh_close_session, ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• proc_exec, proc_sudo, proc_exec_stream

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename

• file_upload, file_download

• ensure_package, ensure_service, ensure_lines_in_file, patch_apply

• os_detect, get_metrics

• tunnel_local_forward, tunnel_remote_forward, tunnel_list, tunnel_close

All tools return text plus stable structuredContent. Tool metadata includes titles, output schemas, and annotations that disclose read-only, destructive, idempotent, and external side-effect behavior.

Resources And Prompts

Resources:

• mcp-ssh-tool://sessions/active

• mcp-ssh-tool://metrics/json

• mcp-ssh-tool://metrics/prometheus

• mcp-ssh-tool://ssh-config/hosts

• mcp-ssh-tool://policy/effective

• mcp-ssh-tool://audit/recent

• mcp-ssh-tool://capabilities/support-matrix

Prompts:

• safe-connect

• inspect-host-capabilities

• plan-mutation

• managed-config-change

Support Matrix

Client Examples

ChatGPT or Claude Desktop:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

VS Code or Cursor:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool"
    }
  }
}

MCP Inspector over HTTP:

printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token

Configuration

High-value environment variables:

Deprecated aliases STRICT_HOST_KEY_CHECKING and SSH_MCP_STRICT_HOST_KEY are still accepted for one v2 compatibility cycle. Prefer SSH_MCP_HOST_KEY_POLICY.

Development

Use the exact local runtime from .nvmrc / .node-version, then run:

npm ci
npm run check

Live SSH suites are opt-in:

RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e

Local quality gates are layered:

• pre-commit: formats staged files and lints staged TypeScript only

• pre-push: runs npm run check:push

• task hooks: runs tracked npm hooks plus .pre-commit-config.yaml hooks when pre-commit is installed

• manual/full parity: task ci or npm run check

CI/CD Ownership

The personal repository https://github.com/oaslananka/mcp-ssh-tool is the canonical source repository. Automatic CI/CD, supply-chain security checks, trusted npm publishing, and MCP Registry publishing run only from https://github.com/oaslananka-lab/mcp-ssh-tool. The org repository pulls from canonical source; personal-repo push and publish workflows are disabled.

The npm package repository.url intentionally points at the org repository so npm provenance can verify that the published artifact came from the same GitHub Actions repository that built it.

See docs/ci-cd-topology.md for org sync, release flow, and manual fallback guidance.

Documentation

• ARCHITECTURE.md

• SECURITY_DECISIONS.md

• MIGRATION.md

• docs/ci-cd-topology.md

• docs/development.md

• docs/release.md

• docs/doppler.md

• docs/operations.md

• docs/branch-protection.md

• docs/maintenance-policy.md

• docs/api-stability.md

• docs/threat-model.md

• docs/configuration.md

• docs/security-model.md

• docs/troubleshooting.md

• docs/enterprise-deployment.md

License

MIT License. See LICENSE.