ssh MCP server
Commit Nov 14, 2026Provides controlled SSH command execution and SFTP file operations on configured hosts for MCP clients.
Also known as ralscha/ssh-mcp
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is ssh MCP?
ssh provides controlled SSH command execution and SFTP file operations on configured hosts for MCP clients. It exposes 17 tools, such as list-connections, read-command, run-command.
Summary generated from the project's README
About ssh MCP server
Managing remote servers through controlled SSH and SFTP operations is what ssh-mcp enables for developers using MCP clients. This server provides a security-conscious bridge to configured hosts, allowing for command execution and file manipulation without providing a full interactive terminal. It supports various authentication methods including private keys, SSH-agent, and Windows Pageant, and can import existing OpenSSH configurations to handle complex jump host or bastion setups.
Users interact with the server through specific tools like read-command for safe inspections, run-command for broader tasks, and a suite of SFTP tools for file management. The server prioritizes safety by using policy-gated commands, shell-quoted templates, and human approval for risky operations. It also features atomic file writes, checksum verification, and a tamper-evident audit log to ensure all actions are recorded and verifiable. It can be run via stdio or through an authenticated Streamable HTTP transport.
What you can do with it
- 1Atomic configuration updatesInstruct the AI to apply a specific code patch to a remote file after verifying its current integrity.
- 2Managed background processesRequest the AI to start a long-running task on a remote host and monitor its progress.
- 3Secure file transfersHave the AI upload a new configuration file to a remote directory using atomic write operations.
Written from the project's README. Every use case is checked against a quote from it.
ssh MCP tools 17
Detected from the READMElist-connectionsread-commandrun-commandlist-command-templatesrun-command-templatediagnose-connectionstart-commandsftp-uploadsftp-downloadsftp-readsftp-checksumsftp-write
| list-connections | — | |
| read-command | — | |
| run-command | — | |
| list-command-templates | — | |
| run-command-template | — | |
| diagnose-connection | — | |
| start-command | — | |
| sftp-upload | — | |
| sftp-download | — | |
| sftp-read | — | |
| sftp-checksum | — | |
| sftp-write | — |
Show all 17 toolsShow fewer tools
sftp-apply-patchsftp-mkdirsftp-renamesftp-removerisky
| sftp-apply-patch | — | |
| sftp-mkdir | — | |
| sftp-rename | — | |
| sftp-remove | — | |
| risky | — |
Configuration
SSH_MCP_DEV_KEY_PASSPHRASE
| Name | Description | |
|---|---|---|
| SSH_MCP_DEV_KEY_PASSPHRASE | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableralscha/ssh-mcp is public and reachablegithub.com/ralscha/ssh-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/ralscha/ssh-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubssh-mcp
A small, security-conscious Model Context Protocol server that gives MCP clients controlled SSH access to configured hosts. It uses the official Go MCP SDK, x/crypto/ssh, and SFTP.
The server supports:
- reusable SSH connections with password, private-key, SSH-agent, or native Windows Pageant authentication;
- optional selection of one Pageant/agent key by SHA-256 fingerprint;
- OpenSSH config imports and chained
ProxyJump/bastion connections; - strict
known_hostsverification or an exact SHA-256 host-key pin; - policy-gated read-only, general, and shell-quoted template commands;
- human approval for risky operations through MCP elicitation/multi-round-trip input;
- command timeouts, cancellation, bounded output, optional PTY, and stdin;
- server-enforced SFTP timeouts and bounded HTTP request bodies;
- persistent background jobs, progress notifications, and the stable MCP Tasks extension;
- structured, bounded SFTP listing, stat, range reads, checksums, atomic writes, and guarded unified patches;
- structured directory creation, rename, and non-recursive removal;
- tamper-evident, redacted JSONL auditing;
- stdio plus authenticated Streamable HTTP transport, including OAuth introspection mode.
The server deliberately does not provide an interactive terminal. Commands remain bounded requests or cancellable background jobs so policy, auditing, and output limits continue to apply. Root logins and profiles without a command allowlist fail closed unless their explicit opt-ins are set.
Installation
Download a release archive for your platform from the repository's Releases page, verify it against checksums.txt, and place ssh-mcp (or ssh-mcp.exe) on your PATH.
Build
Go 1.27 or newer is expected by this module:
go build -o ssh-mcp.exe ./cmd/ssh-mcp
go test ./...
On Linux or macOS, use -o ssh-mcp instead.
Run ssh-mcp --version to verify the installed build. Version 1.0.0 release archives contain the executable, this README, the license, and the example configuration.
Configure
Copy config.example.toml to the platform config path:
| Platform | Default path |
|---|---|
| Linux | ~/.config/ssh-mcp/config.toml |
| macOS | ~/Library/Application Support/ssh-mcp/config.toml |
| Windows | %AppData%\ssh-mcp\config.toml |
You can also pass --config PATH. On Unix, the config must not be readable or writable by group/others; use chmod 600.
Passwords and private-key passphrases are read only from environment variables. For a profile named prod-web, resolution is:
SSH_MCP_PROD_WEB_PASSWORD, thenSSH_MCP_PASSWORD;SSH_MCP_PROD_WEB_KEY_PASSPHRASE, thenSSH_MCP_KEY_PASSPHRASE.
For agent authentication, set auth = "agent". On Linux and macOS the server uses SSH_AUTH_SOCK. On Windows it automatically uses native PuTTY Pageant when Pageant is running, with no bridge or SSH_AUTH_SOCK required; otherwise it tries the Windows OpenSSH agent at \\.\pipe\openssh-ssh-agent. Pageant must already be running with at least one suitable key loaded.
If an agent contains many keys, set agentKeyFingerprint = "SHA256:..." on the profile. Only that key is offered, avoiding MaxAuthTries failures. diagnose-connection lists the loaded public-key fingerprints and reports which one is selected; it never returns private material.
OpenSSH config and jump hosts
Set sshConfigHost on a profile to fill missing HostName, User, Port, IdentityFile, and ProxyJump values from ~/.ssh/config:
[[profiles]]
name = "production"
sshConfigHost = "prod-web"
Alternatively, defaults.importSSHHosts = ["prod-web", "staging"] creates profiles for exact aliases. A referenced ProxyJump alias is imported automatically as a jump-only profile: it can carry the SSH connection but cannot be targeted by MCP tools. Explicit TOML values override imported OpenSSH values. Include directives and wildcard/negated Host patterns are supported; conditional Match blocks are intentionally ignored. For multiple hops, chain configured profiles with proxyJump rather than using a comma-separated OpenSSH value.
Host-key verification is strict by default. The server uses knownHostsFile, normally ~/.ssh/known_hosts, unless trustedHostKey pins an exact SHA256:... fingerprint. hostKeyMode = "insecure" and per-profile insecureSkipHostKey = true exist for isolated test hosts and emit a warning; do not use them for real systems.
MCP client setup
Build the executable, then add it to your MCP client's configuration:
{
"mcpServers": {
"ssh": {
"command": "C:\\path\\to\\ssh-mcp.exe",
"args": ["--config", "C:\\path\\to\\config.toml"],
"env": {
"SSH_MCP_DEV_KEY_PASSPHRASE": "optional-passphrase"
}
}
}
}
If the default config file does not exist, the MCP handshake and tools/list still work, but every tool call returns a clear unconfigured error.
Tools
| Tool | Purpose |
|---|---|
list-connections |
List profiles and lazy connection state. |
read-command |
Run one conservative, allowlisted read-only command without shell operators. |
run-command |
Run a command after built-in and configured policy checks. |
list-command-templates |
List narrowly scoped operations configured for a profile. |
run-command-template |
Render a template with shell-quoted arguments, then apply normal policy. |
diagnose-connection |
Test DNS, direct/proxied TCP, agent keys, host key, and authentication separately. |
start-command |
Start a persistent, cancellable background command. |
job-status, job-output, cancel-job |
Poll and manage a background job by its unguessable ID on clients without Tasks support. |
sftp-upload |
Atomically upload UTF-8 or base64 content. Mutating; denied on read-only profiles. |
sftp-download |
Download a bounded file as UTF-8 or base64. |
sftp-list, sftp-stat |
Inspect directories and path metadata. |
sftp-read |
Read a bounded file byte range. |
sftp-checksum |
Calculate a bounded remote file's SHA-256. |
sftp-write |
Alias for atomic sftp-upload. |
sftp-apply-patch |
Apply a unified diff after checking the current SHA-256, then atomically replace the file. |
sftp-mkdir |
Create a directory, optionally including missing parents. |
sftp-rename |
Rename a path, with explicit opt-in for destination replacement. |
sftp-remove |
Remove one file, symlink, or empty directory; recursive deletion is not supported. |
audit-list, audit-verify |
Read redacted events and verify the hash chain. |
read-command recognizes common inspection commands such as ls, cat, grep, ps, stat, systemctl status/show, docker ps/logs/inspect, and kubectl get/logs/describe. It rejects shell operators and redirection. Git is intentionally excluded because repository configuration can invoke helper programs and some nominally observational Git commands can update the index; expose a deliberately constrained Git command template if needed.
run-command is broader, but always blocks a narrow catastrophic set such as filesystem formatting, dd ... of=/dev/..., root-recursive removal, shutdown/reboot, pipe-to-shell installers, fork bombs, and destructive root permission changes. These rules reduce accidents; they are not a shell sandbox. A profile must configure at least one allowedCommands expression before run-command or start-command can be used. Setting allowUnrestrictedCommands = true bypasses only that allowlist requirement and should be reserved for isolated, trusted environments; built-in and configured deny rules still apply.
When allowedCommands is non-empty, a command must match at least one expression. Global and per-profile denyCommands are applied first. Invalid regular expressions stop startup.
Command templates use {{parameter}} placeholders. Every supplied value is POSIX-shell quoted, undeclared or missing arguments are rejected, and the rendered command still passes through the same deny/allow and catastrophic-command checks. Set readOnly = true only for a genuinely non-mutating template; requiresApproval = true forces confirmation.
Approvals
approvalMode can be set globally or per profile:
risky(default) requests confirmation for privilege escalation, service/package/firewall changes, deletion, permission changes, selected Git/container/Kubernetes mutations, shell redirection, file replacement, and patching;alwaysrequests confirmation for every mutating action;neverrelies on server policy without interactive confirmation.
Current MCP sessions receive an InputRequests approval and automatically retry after the user answers. Older sessions use elicitation through the SDK compatibility flow. Declined, missing, expired, modified, or unsupported approvals fail closed. Catastrophic commands remain blocked and cannot be approved.
Background jobs and MCP Tasks
start-command returns a normal job object to ordinary clients. Clients that declare io.modelcontextprotocol/tasks in their per-request extension capabilities receive a stable 2026-07-28 CreateTaskResult instead and can call tasks/get, tasks/cancel, and tasks/update. The server only returns the polymorphic Task result after explicit client opt-in.
Job metadata and bounded output are persisted to jobStateFile; command strings are intentionally not persisted. Running jobs are marked failed after a server restart because SSH cannot reattach to an already detached process. Completed handles remain pollable until jobRetentionMs expires. Clients must retain the job ID returned by start-command; there is intentionally no global job-list tool because a list can disclose other callers' task handles. Non-Tasks callers with a progress token receive start and terminal progress notifications.
SFTP mode is a JSON integer: Unix 0600 is decimal 384, and 0644 is decimal 420. Omit it for 0600.
sftp-apply-patch requires expectedSha256, normally obtained from sftp-checksum. The checksum is rechecked immediately before upload. SFTP has no portable compare-and-swap primitive, so another writer can still race the final rename; use remote OS permissions or a command template with application-specific locking when strict cross-process serialization is required. Patch targets must be regular UTF-8 files; symlinks, directories, and special files are rejected.
Writes use a sibling temporary file, request an SFTP fsync when supported, and use the OpenSSH POSIX rename extension for atomic replacement. If the destination exists and that extension is unavailable, the write fails instead of silently degrading to a non-atomic replacement.
Audit log
Set defaults.auditLog to enable append-only JSONL auditing. Events include the profile, action, redacted command or target, authorization decision, outcome, duration, exit code, and transferred byte count. Each event hashes its content and the previous event hash; startup and audit-verify reject a modified chain. The log is forced to owner-only permissions where the platform supports them.
Built-in redaction covers common password/token/secret assignments, bearer tokens, and PEM private keys. Add installation-specific regular expressions with defaults.auditRedact. Avoid putting secrets directly in commands in the first place; use the server's environment-based credential resolution.
Streamable HTTP and OAuth
Stdio is the default. Set [http].enabled = true to serve stateless Streamable HTTP at listen plus path, including MCP revision 2026-07-28. authMode = "token" compares the bearer credential against tokenEnv in constant time. Non-loopback listeners require a TLS certificate and key, and browser origins must be same-origin or explicitly listed in allowedOrigins. Requests larger than maxRequestBytes are rejected with HTTP 413.
For a shared deployment, authMode = "oauth":
- publishes OAuth protected-resource metadata at the RFC 9728 path derived from
resourceUrl(for example/.well-known/oauth-protected-resource/mcp) with the pathless endpoint retained for compatibility; - challenges unauthenticated requests with
WWW-Authenticateandresource_metadata; - validates access tokens through RFC 7662 introspection;
- verifies expiry, audience/resource, and every configured required scope;
- caches only a SHA-256 token identifier and the short-lived validation result, never the token itself.
The OAuth introspection client ID and secret come from oauthClientIdEnv and oauthClientSecretEnv. The authorization server, resource URL, and introspection endpoint must use HTTPS.
Security notes
- Avoid root SSH accounts.
- If root access is unavoidable, it must be acknowledged with
allowRoot = true; use a dedicated profile with a very narrow allowlist and approval modealways. - Prefer a dedicated remote user with OS-level permissions matching the task.
- Keep strict host-key verification enabled.
- Use a narrow
allowedCommandslist for production profiles. - Prefer command templates over arbitrary
run-commandaccess. - Mark inspection-only profiles with
readOnly = true; this disablesrun-commandand uploads. - Keep
approvalMode = "risky"oralwaysunless the MCP client cannot present approvals. - Keep HTTP on loopback unless TLS and OAuth are configured.
- OAuth scopes authorize the server as a whole; for tenant- or user-specific profile isolation, run separate instances with separate configuration, audit, and job-state files.
- Run only one server process per
auditLogandjobStateFile; these files use atomic replacement and process-local synchronization, not cross-process locking. - MCP tool annotations are hints to clients, not access controls. Enforcement happens in the server before opening an SSH channel.
Development
gofmt -w cmd internal
go vet ./...
go test ./...
go build ./cmd/ssh-mcp
The repository also includes the same Taskfile, GoReleaser, lint configuration, and test/release workflow layout used by jira-mcp. Run task check for the local release gate.
License
MIT - see LICENSE.
ssh MCP questions
What tools does ssh MCP provide?
It exposes 17 tools, including list-connections, read-command, run-command, list-command-templates, run-command-template.
How can I authenticate with the server?
The server supports password, private-key, SSH-agent, or native Windows Pageant authentication.
Can I use my existing OpenSSH configuration?
Yes, you can set sshConfigHost on a profile to import HostName, User, Port, IdentityFile, and ProxyJump values from your ~/.ssh/config.
Is the command execution safe?
The server uses policy-gated commands, command timeouts, and can require human approval for risky operations through MCP elicitation.
Does it support background jobs?
Yes, it supports persistent background jobs with progress notifications and the MCP Tasks extension.