ssh-mcp-pro
ssh-mcp-pro is a policy-controlled MCP server for secure SSH automation, offering safe remote-connector discovery plus full-profile host administration tools.
Manage SSH sessions: open/close/list/ping sessions, list/resolve configured hosts, and enforce strict host-key or explain-only policy modes.
Run remote commands: non-interactive and streaming execution, sudo only when allowed, process listing/signaling, and OS detection.
Work with files: read/write/stat/list, create directories, rename/remove recursively, apply patches, and ensure lines in files.
Transfer files over SFTP with SHA-256 verification and create/list/close local or remote SSH tunnels.
Perform idempotent package and service management: ensure package/service state, list/status/logs, restart/stop services.
Inspect system health and diagnostics: disk, memory, CPU, network interfaces, port checks, log tails, and runtime metrics.
Preview safe actions: explain policy decisions, plan mutations without executing, and show connector/host readiness with secrets redacted.
Apply tool profiles for remote-safe/ChatGPT/Claude use and security defaults that block root login, raw sudo, destructive commands, and destructive filesystem operations unless explicitly allowed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ssh-mcp-pro connect to prod-db and run 'df -h'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.2or>=24.15.0or>=26.3.0pnpm
^11.28.11(use Corepack for development)SSH access to the target hosts
Docker, only for local integration tests and container image builds
Related MCP server: mcpx
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-pro
ssh-mcp-pro --versionRun without a global install:
npx ssh-mcp-proFor pnpm-only environments, use:
pnpm dlx ssh-mcp-proContainer images are published to GitHub Container Registry for release tags:
docker run --rm ghcr.io/oaslananka/ssh-mcp-pro:1.4.1 --versionImages 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.
Cloud dashboard and AI connectors
The optional ssh-mcp-pro Cloud lets you sign in with Google or GitHub, enroll your own devices, and connect an OAuth-capable AI client to https://ssh-mcp-pro.oaslananka.dev/mcp. Your SSH private keys remain on your devices.
After installing the package, start a local web dashboard with one command:
ssh-mcp-pro webThe shortcut binds only to http://127.0.0.1:3000/dashboard and does not publish a privileged server to your network. Signing in requires your own configured GitHub or Google OAuth application. For hosted, multi-user operation use the production control plane configuration; the localhost command is for local development and testing.
The hosted service serves Privacy and Terms. Operators may enable an owner-only Usage & Users tab by setting SSH_MCP_DASHBOARD_OWNER_GITHUB_LOGINS and/or SSH_MCP_DASHBOARD_OWNER_GOOGLE_EMAILS; global usage access is disabled by default. The separately gated OpenAI reviewer sandbox uses a dedicated sample-only identity and is not a general sign-in method.
See Web publication readiness for ChatGPT, Claude, and Gemini connection steps and independent acceptance requirements. Manifest validation alone does not mean any platform has approved the plugin.
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.
General computer control through the hosted connector
Once a user has enrolled a computer, ChatGPT, Claude or another authorized MCP client can manage it using generic tools, regardless of whether the computer has Git, Docker, a database, or other applications installed:
Run an installed application:
run_shellor the managedprocess_start,process_read,process_inputandprocess_stoptools. The shell is the native PowerShell on Windows orshon Unix.Find and inspect files:
file_search,file_content_search,file_inspect(stat/list) andfile_read.Manage project files:
file_manage(mkdir,copy,move,remove),file_write, and the preview/expected-hashfile_replace. Directory listings and file searches are bounded. File management operates on the selected device itself rather than transferring entire files through the AI conversation.
Choose Full Admin for a device when you want unrestricted access within that operating-system user account. New Full Admin profiles can work with ordinary home, project and mounted-disk paths; the OS account still determines whether an operation succeeds. The device owner's saved custom allow/deny rules still take priority. Existing enrolled devices retain their saved policies until the owner edits them in the dashboard. OAuth scopes separately control which of those device operations a connected AI client may request.
Dedicated Docker MCP tools are no longer advertised to newly connecting clients. Previously authorized clients may still use the legacy Docker tool names during the compatibility period; new users can call an installed application's own CLI through the generic shell instead. This does not provide GUI screen, mouse, keyboard or browser interaction: those require desktop-session integration and OS accessibility/screen permissions.
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 |
|
| Maximum concurrent SSH sessions. |
|
| Session time-to-live in milliseconds. |
|
| Default remote command timeout in milliseconds. |
|
| Maximum buffered stdout/stderr bytes per command result. |
|
| Maximum retained streaming chunks. |
|
| Maximum bytes returned by text-focused file reads. |
|
| Maximum accepted write payload before buffering. |
|
| Maximum upload or download transfer size. |
|
| Enables debug-oriented configuration behavior. |
|
| Enables the global MCP request rate limiter. |
|
| Maximum requests per rate-limit window. |
|
| Enables per-session MCP request rate limiting when tool arguments include |
|
| Maximum requests per SSH session per rate-limit window. |
|
| Per-session rate-limit window in milliseconds. |
|
| Rate-limit window in milliseconds. |
| unset | Legacy boolean alias for strict vs insecure host-key checking. |
|
| Host-key mode: |
|
| Known hosts file used for strict host-key verification. |
|
| Allows SSH login as root and mirrors into policy. |
| empty | Optional SSH cipher allowlist. |
| unset | JSON file containing partial policy overrides. |
|
| Policy decision mode: |
|
| Allows raw |
|
| Allows commands matching destructive command policy. |
|
| Allows destructive filesystem operations such as |
| empty | Host allowlist for policy and remote connector safety checks. |
| empty | Command allow patterns. |
| empty | Command deny patterns. |
|
| Remote path prefixes allowed by filesystem policy. |
|
| Remote path prefixes denied by filesystem policy. |
| OS temp directory | Local paths allowed for transfer operations. |
| empty | Local paths denied for transfer operations. |
|
| Local bind hosts allowed for tunnels. |
|
| Local bind hosts denied for tunnels. |
| empty | Optional remote tunnel target host allowlist. |
| empty | Optional remote tunnel target host denylist. |
| empty | Optional tunnel port allowlist. |
| empty | Optional tunnel port denylist. |
|
| Streamable HTTP bind host. |
|
| Streamable HTTP bind port. |
|
| Browser origins allowed for HTTP clients. |
| unset | Bearer token file for HTTP transport. Required for non-loopback bearer deployments. |
|
| Enables legacy SSE compatibility. |
|
| Maximum HTTP request body size. |
|
| Maximum 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 |
|
| HTTP MCP session idle timeout in milliseconds. Use |
| unset | Stable public HTTPS MCP URL for protected resource metadata. |
|
| Trust reverse proxy forwarded headers. |
|
| Active tool exposure profile. |
|
| Alias for |
|
| Credential provider: |
| unset | External credential command when provider is |
| empty | Arguments passed to the external credential command. |
|
| Credential command timeout in milliseconds. |
| unset | Default username for connector broker flows. |
|
| HTTP auth mode: |
| unset | Expected OAuth issuer. |
| unset | Expected OAuth audience. |
| unset | OAuth JWKS URL. |
| unset | OAuth protected resource identifier. |
|
| Required OAuth scopes. |
| unset | Optional comma-separated JWT algorithm allowlist, for example |
| unset | Optional dedicated OpenAI reviewer username. Reviewer access remains disabled unless the matching scrypt hash is also configured. |
| unset | Optional scrypt hash for the dedicated OpenAI reviewer account; never store the plaintext password here. See OpenAI Reviewer Sandbox. |
| unset | When enabled with |
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 |
| All SSH, process, filesystem, transfer, ensure, tunnel, connector, and system tools. | All runtime resources. | All prompts. |
|
|
|
|
| Baseline remote connector tools plus an empty ChatGPT extension set. | Same remote connector subset as | Same remote connector subset as |
| Baseline remote connector tools plus an empty Claude extension set. | Same remote connector subset as | Same remote connector subset as |
| Same remote connector subset as | Same remote connector subset as | Same remote connector subset as |
| Same remote connector subset as | Same remote connector subset as | Same remote connector subset as |
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 project-authored source is available under GNU AGPL v3.0.
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.
File | Purpose |
Claude Code-valid product plugin manifest. | |
Claude Code project-local MCP server configuration. | |
Codex CLI MCP configuration example. | |
VS Code / GitHub Copilot workspace MCP configuration example. | |
OpenCode project MCP configuration example. | |
| OpenCode-native mirrored skill definitions. |
Agent runtime setup and validation notes. |
Validate plugin packaging locally:
claude plugin validate .Available Tools
46 toolsconnector_statusConnector StatusARead-onlyIdempotent
Use this when ChatGPT or Claude needs to understand the remote connector profile, authentication mode, and credential broker readiness without exposing secrets.
Inputs: no named parameters. Returns: Remote connector readiness without secrets
cpu_usageCPU UsageARead-onlyIdempotent
Reports CPU load average and uptime on the remote system
Inputs: sessionId (required). Returns: Remote command result
disk_usageDisk UsageARead-onlyIdempotent
Reports disk usage for filesystems on the remote system
Inputs: sessionId (required), path. Returns: Remote command result
ensure_lines_in_fileEnsure Lines In FileADestructiveIdempotent
Ensures specific lines are present or absent in a file
Inputs: path (required), lines (required), sessionId (required), state, +1 more. Returns: Line management result
ensure_packageEnsure Package StateBDestructiveIdempotent
Ensures a package is installed or removed
Inputs: name (required), sessionId (required), state. Returns: Package state result
ensure_serviceEnsure Service StateADestructiveIdempotent
Ensures a service is in the desired state
Inputs: name (required), state (required), sessionId (required). Returns: Service state result
file_downloadDownload FileARead-only
Downloads a remote file to the local machine over SFTP
Inputs: localPath (required), sessionId (required), remotePath (required). Returns: File transfer result with integrity details
file_uploadUpload FileADestructive
Uploads a local file to the remote host over SFTP
Inputs: localPath (required), sessionId (required), remotePath (required). Returns: File transfer result with integrity details
fs_listList Remote DirectoryARead-onlyIdempotent
Lists directory contents
Inputs: path (required), sessionId (required), page, limit. Returns: Remote directory entries
fs_mkdirpCreate Remote DirectoriesAIdempotent
Creates directories recursively
Inputs: path (required), sessionId (required). Returns: Remote file operation result
fs_readRead Remote FileBRead-onlyIdempotent
Reads a file from the remote system
Inputs: path (required), sessionId (required), encoding, maxBytes. Returns: Remote file content
fs_renameRename Remote PathBDestructive
Renames or moves a file/directory
Inputs: to (required), from (required), sessionId (required). Returns: Remote file operation result
fs_rmrfRemove Remote Path RecursivelyADestructive
Removes files or directories recursively
Inputs: path (required), sessionId (required). Returns: Remote file operation result
fs_statStat Remote PathBRead-onlyIdempotent
Gets file or directory statistics
Inputs: path (required), sessionId (required). Returns: Remote path stat result
fs_writeWrite Remote FileADestructive
Writes data to a file on the remote system
Inputs: data (required), path (required), sessionId (required), mode. Returns: Remote file operation result
get_metricsGet Runtime MetricsARead-onlyIdempotent
Returns server metrics including session counts, command statistics, and uptime
Inputs: format. Returns: Runtime metrics
log_tailTail LogARead-onlyIdempotent
Tails the end of a log file or reads recent journal entries for a service
Inputs: sessionId (required), path, lines, service. Returns: Remote command result
memory_infoMemory InfoARead-onlyIdempotent
Reports memory usage on the remote system
Inputs: sessionId (required). Returns: Remote command result
net_interfacesNetwork InterfacesARead-onlyIdempotent
Lists network interfaces and their IP addresses on the remote system
Inputs: sessionId (required). Returns: Remote command result
os_detectDetect Remote OSARead-onlyIdempotent
Detects operating system and environment information
Inputs: sessionId (required). Returns: Remote operating system information
patch_applyApply PatchBDestructive
Applies a patch to a file
Inputs: diff (required), path (required), sessionId (required). Returns: Patch application result
port_checkPort CheckBRead-onlyIdempotent
Checks which processes are listening on a specific port
Inputs: port (required), sessionId (required), host. Returns: Remote command result
proc_execExecute Remote CommandA
Executes a non-interactive command on the remote system after policy and safety checks
Inputs: command (required), sessionId (required), cwd, env, +1 more. Returns: Remote command result
proc_exec_streamExecute Streaming CommandB
Executes a command and returns streaming output chunks
Inputs: command (required), sessionId (required), cwd, env, +1 more. Returns: Streaming command result with output chunks
proc_killSignal ProcessBDestructive
Sends a signal to a running process by PID
Inputs: pid (required), sessionId (required), signal. Returns: Remote command result
proc_listList ProcessesARead-onlyIdempotent
Lists running processes on the remote system sorted by CPU usage
Inputs: sessionId (required). Returns: Remote command result
proc_sudoExecute Sudo CommandADestructive
Executes a command with sudo privileges only when allowRawSudo policy permits it
Inputs: command (required), sessionId (required), cwd, timeoutMs. Returns: Remote command result
service_listList ServicesARead-onlyIdempotent
Lists all systemd services and their current state
Inputs: sessionId (required). Returns: Remote command result
service_logsService LogsARead-onlyIdempotent
Reads recent journal logs for a systemd service
Inputs: name (required), sessionId (required), lines. Returns: Remote command result
service_restartRestart ServiceB
Restarts a systemd service
Inputs: name (required), sessionId (required). Returns: Remote command result
service_statusService StatusBRead-onlyIdempotent
Gets the status of a systemd service
Inputs: name (required), sessionId (required). Returns: Remote command result
service_stopStop ServiceADestructive
Stops a systemd service
Inputs: name (required), sessionId (required). Returns: Remote command result
ssh_close_sessionClose SSH SessionBIdempotent
Closes an SSH session
Inputs: sessionId (required). Returns: Session close result
ssh_host_inspectInspect SSH HostARead-only
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.
Inputs: hostAlias (required), checks. Returns: Read-only host inspection result
ssh_hosts_listList Safe SSH Host AliasesARead-onlyIdempotent
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.
Inputs: no named parameters. Returns: Redacted SSH host aliases allowed by policy
ssh_list_configured_hostsList Configured HostsARead-onlyIdempotent
Lists all hosts configured in ~/.ssh/config
Inputs: no named parameters. Returns: Configured SSH host aliases
ssh_list_sessionsList SSH SessionsARead-onlyIdempotent
Lists all active SSH sessions with their details
Inputs: no named parameters. Returns: Active SSH sessions
ssh_mutation_planPlan SSH MutationARead-onlyIdempotent
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.
Inputs: goal (required), hostAlias (required), category. Returns: Non-executing remote mutation plan
ssh_open_sessionOpen SSH SessionB
Opens a new SSH session with authentication
Inputs: host (required), username (required), auth, port, +12 more. Returns: Session creation result or explain-mode connection plan
ssh_pingPing SSH SessionARead-onlyIdempotent
Checks if an SSH session is still alive and responsive
Inputs: sessionId (required). Returns: Session health check result
ssh_policy_explainExplain SSH PolicyARead-onlyIdempotent
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.
Inputs: path, action, command, hostAlias. Returns: Explain-only policy decision
ssh_resolve_hostResolve SSH HostARead-onlyIdempotent
Resolves a host alias from ~/.ssh/config to connection parameters
Inputs: hostAlias (required). Returns: Resolved SSH connection parameters
tunnel_closeClose SSH TunnelBIdempotent
Closes an active tunnel
Inputs: tunnelId (required). Returns: Tunnel close result
tunnel_listList SSH TunnelsARead-onlyIdempotent
Lists active tunnels, optionally filtered by session
Inputs: sessionId. Returns: Active SSH tunnels
tunnel_local_forwardCreate Local SSH TunnelC
Creates a local SSH port forward
Inputs: localPort (required), sessionId (required), remoteHost (required), remotePort (required). Returns: SSH tunnel info
tunnel_remote_forwardCreate Remote SSH TunnelB
Creates a remote SSH port forward
Inputs: localHost (required), localPort (required), sessionId (required), remotePort (required). Returns: SSH tunnel info
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
Several tool pairs have blurred boundaries: ssh_list_configured_hosts vs ssh_hosts_list both enumerate hosts, log_tail vs service_logs both read journal entries for a service, and ensure_service overlaps with service_restart/service_stop/service_status. proc_sudo vs proc_exec and ssh_host_inspect vs ssh_resolve_host also require the agent to reason about subtle policy differences rather than purpose.
The set follows a clear domain-prefix convention (fs_*, ssh_*, service_*, proc_*, tunnel_*, file_*), which makes names scannable and mostly predictable. Minor deviations exist: get_metrics uses verb_noun while peers use noun_verb, os_detect is noun_verb amid prefix-first names, and ssh_list_sessions vs ssh_hosts_list invert the ordering within the same family.
46 tools is heavy for what is essentially remote host administration, and the surface shows signs of accretion (multiple logging tools, duplicate host-listing tools, both proc_exec and proc_exec_stream, both connector_status and get_metrics). A single SSH server would be more legible with roughly half this count by merging overlapping families.
Coverage is broad for the domain: session lifecycle, filesystem CRUD and stats, package/service management, process control, tunnels, transfers, metrics, and a policy/planning layer. Gaps are minor — no user/group or cron/scheduled-task management, and no explicit package listing, but agents can reach those via proc_exec.
Maintenance
Related MCP Connectors
SSH client, server management and one remote MCP URL for your machines, with human approvals.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Related MCP Servers
- AlicenseAqualityAmaintenanceSSH automation MCP server that enables Claude and ChatGPT to execute commands, manage files, install packages, and control services on remote servers over SSH — supporting password, key, and agent authentication.331,267 npm4MIT
- AlicenseBqualityBmaintenanceA Model Context Protocol server for complete shell and SSH mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls.18153 PyPI3Apache 2.0
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) SSH client server that provides autonomous SSH operations for GitHub Copilot and VS Code. Enable natural language SSH automation without manual prompts or GUI interactions.202MIT
- AlicenseNot gradedqualityDmaintenanceSSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.ISC