Ssh Mcp Pro
About
TypeScript MCP server for controlled SSH operations, remote host workflows, command execution guardrails, and infrastructure automation.
Details
- Author
- oaslananka
- GitHub stars
- 1
- Downloads
- 221
Jump to
- 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
- INSTALL.md covers full client setup and troubleshooting
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Ssh Mcp ProCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The README includes setup instructions such as npx ssh-mcp-pro.
connector_status
Use this when ChatGPT or Claude needs to understand the remote connector profile, authentication mode, and credential broker readiness without exposing secrets.
ssh_hosts_list
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.
ssh_policy_explain
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.
ssh_host_inspect
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.
ssh_mutation_plan
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.
ssh_open_session
Opens a new SSH session with authentication
ssh_close_session
Closes an SSH session
ssh_list_sessions
Lists all active SSH sessions with their details
ssh_ping
Checks if an SSH session is still alive and responsive
ssh_list_configured_hosts
Lists all hosts configured in ~/.ssh/config
ssh_resolve_host
Resolves a host alias from ~/.ssh/config to connection parameters
proc_exec
Executes a non-interactive command on the remote system after policy and safety checks
proc_sudo
Executes a command with sudo privileges only when allowRawSudo policy permits it
proc_list
Lists running processes on the remote system sorted by CPU usage
proc_kill
Sends a signal to a running process by PID
proc_exec_stream
Executes a command and returns streaming output chunks
fs_read
Reads a file from the remote system
fs_write
Writes data to a file on the remote system
fs_stat
Gets file or directory statistics
fs_list
Lists directory contents
fs_mkdirp
Creates directories recursively
fs_rmrf
Removes files or directories recursively
fs_rename
Renames or moves a file/directory
ensure_package
Ensures a package is installed or removed
ensure_service
Ensures a service is in the desired state
ensure_lines_in_file
Ensures specific lines are present or absent in a file
patch_apply
Applies a patch to a file
os_detect
Detects operating system and environment information
get_metrics
Returns server metrics including session counts, command statistics, and uptime
service_list
Lists all systemd services and their current state
service_status
Gets the status of a systemd service
service_logs
Reads recent journal logs for a systemd service
service_restart
Restarts a systemd service
service_stop
Stops a systemd service
disk_usage
Reports disk usage for filesystems on the remote system
memory_info
Reports memory usage on the remote system
cpu_usage
Reports CPU load average and uptime on the remote system
net_interfaces
Lists network interfaces and their IP addresses on the remote system
port_check
Checks which processes are listening on a specific port
log_tail
Tails the end of a log file or reads recent journal entries for a service
file_upload
Uploads a local file to the remote host over SFTP
file_download
Downloads a remote file to the local machine over SFTP
tunnel_local_forward
Creates a local SSH port forward
tunnel_remote_forward
Creates a remote SSH port forward
tunnel_close
Closes an active tunnel
tunnel_list
Lists active tunnels, optionally filtered by session
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"ssh mcp pro": {
"ssh-mcp-pro": {
"command": "npx",
"args": [
"ssh-mcp-pro"
]
}
}
}
}McpServers
{
"ssh-mcp-pro": {
"command": "npx",
"args": [
"ssh-mcp-pro"
]
}
}<h1 align="center">ssh-mcp-pro</h1>
<p align="center">
<a href="https://www.npmjs.com/package/ssh-mcp-pro">
</a>
<a href="https://www.npmjs.com/package/ssh-mcp-pro">
</a>
<a href="LICENSE">
</a>
<a href="https://github.com/oaslananka/ssh-mcp-pro/actions/workflows/ci.yml">
</a>
<a href="https://oaslananka.github.io/ssh-mcp-pro/">
</a>
</p>
<p align="center">
<a href="https://www.buymeacoffee.com/oaslananka">
</a>
</p>
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 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_MS | 900000 | HTTP MCP session idle timeout in milliseconds. Use 300000 for ChatGPT/Cloudflare production deployments where clients may abandon sessions without DELETE. |
| 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. |
| SSH_MCP_OAUTH_ALLOWED_ALGORITHMS | unset | Optional comma-separated JWT algorithm allowlist, for example RS256,ES256. When unset, the built-in OAuth verifier defaults are used. |
| SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGH | unset | When 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.
| 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.
- 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.
| File | Purpose |
| --- | --- |
| .claude-plugin/plugin.json | Claude Code-valid product plugin manifest. |
| .mcp.json | Claude Code project-local MCP server configuration. |
| .codex/config.example.toml | Codex CLI MCP configuration example. |
| .vscode/mcp.example.json | VS Code / GitHub Copilot workspace MCP configuration example. |
| opencode.example.jsonc | OpenCode project MCP configuration example. |
| .opencode/skills/ | OpenCode-native mirrored skill definitions. |
| docs/agent-runtime-config.md | Agent runtime setup and validation notes. |
Validate plugin packaging locally:
claude plugin validate .
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
