ssh-mcp
Provides a tool to test Git-over-SSH authentication to Bitbucket, confirming SSH keys are configured and loaded for reliable git access.
Provides a tool to test Git-over-SSH authentication to GitHub, verifying that SSH keys are correctly configured and loaded for seamless git operations.
Provides a tool to test Git-over-SSH authentication to GitLab, ensuring SSH keys are properly set up for git operations.
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 run 'uptime' on my production server"
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.
@txcxgzs/ssh-mcp
Make SSH work for AI tools. MCP server that manages your SSH environment, diagnoses what's broken, fixes it, and gives your agent remote access to anything.
Fork relationship: This repository is a derivative fork of YawLabs/ssh-mcp. It keeps the upstream SSH/MCP implementation and adds server-side password alias resolution through independent
SSH_CREDENTIAL_<ID>environment variables, removes plaintext passwords from MCP tool arguments, and fixes first-runknown_hostscreation when~/.sshdoes not yet exist. Upstream remains the original project; fork-specific changes are maintained separately here.
The upstream project is built and maintained by Yaw Labs.
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
The problem
AI CLI tools run in subprocesses where SSH is constantly broken. The agent tries to git pull and gets Permission denied (publickey). It tries to SSH into a server and the agent socket is stale. It tries to deploy and the host key changed because the instance was recreated. Every time, the AI has no idea what's wrong and spirals.
This happens across every situation that needs SSH keys:
Git — clone, pull, push, fetch, submodules, LFS
Package managers —
npm install,pip install,go get,cargo,composerfrom private reposServer access — SSH, SCP, SFTP, rsync
Tunneling — port forwarding to databases, SOCKS proxies
Deployment — Ansible, Terraform, Capistrano, deploy scripts
Cloud — AWS EC2, GCP, Azure, DigitalOcean, any VPS
ssh-mcp fixes this. It manages the SSH agent, loads keys, diagnoses failures with actionable fix commands, and provides remote operations — all as MCP tools your AI agent can call.
Related MCP server: MCP SSH Server
Quick start
Add to your MCP client config:
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@txcxgzs/ssh-mcp@latest"],
"env": {
"SSH_CREDENTIAL_SSH1": "your-password"
}
}
}
}On Windows wrap with cmd /c since Node 20+ can't spawn .cmd files directly:
{
"mcpServers": {
"ssh": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@txcxgzs/ssh-mcp@latest"]
}
}
}The @latest tag makes npx re-resolve against the registry on every spawn, so each MCP session uses the newest published version. Or install globally if you'd rather pin (no auto-update):
npm install -g @txcxgzs/ssh-mcp
# then in client config: "command": "ssh-mcp"Tools
SSH environment management
Tools that fix your local SSH setup so everything else — git, deploys, tunnels — stops breaking.
Tool | Description |
| Ensure ssh-agent is running. Starts one if needed and sets env vars for the session. |
| List all SSH keys in ~/.ssh/ with type, fingerprint, and agent status. |
| Load a key into the running agent. Ensures the agent is started first. |
| Resolve the effective SSH config for a host (hostname, user, port, proxy, identity files). |
| Remove a stale host key and re-scan. Fixes "host key verification failed" errors. |
| Test Git-over-SSH auth to GitHub, GitLab, Bitbucket, etc. |
| Quick connectivity test with timing and actionable error details. |
Diagnostics
Tool | Description |
| Full SSH environment diagnostic. Checks agent, keys, config, known_hosts, and connectivity. Returns exact fix commands for every failure. |
Remote operations
Tool | Description |
| Execute a command on a remote host. Returns stdout, stderr, and exit code (or |
| Read a file from a remote host via SFTP. |
| Write content to a file on a remote host via SFTP. |
| Upload a local file to a remote host via SFTP. |
| Download a file from a remote host to local filesystem. |
| List files in a directory on a remote host. |
| Get metadata for a file or directory (size, mode in octal, uid/gid, mtime/atime, isFile/isDirectory/isSymbolicLink). Use instead of parsing |
| Create a directory via SFTP. Set |
| Delete a file or empty directory via SFTP. Auto-dispatches unlink vs rmdir based on the path's type. Recursive directory delete is intentionally NOT supported -- use |
Higher-level operations
Tools that wrap common patterns agents build with ssh_exec — faster and less error-prone.
Tool | Description |
| Run a command on multiple hosts in parallel. Returns results per host. Subject to command policy if configured (policy is checked once before fan-out). |
| Search for files remotely with structured parameters ( |
| Read the last N lines of a file, optionally filtered by a grep pattern. |
| Check systemd service status (active, PID, uptime, description). Flags |
Auto-diagnostics
When any remote operation fails, ssh-mcp automatically runs diagnostics and includes the results in the error response. Your agent doesn't need to call ssh_diagnose separately — it gets told what's wrong and how to fix it right in the error message.
Connection pooling
Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.
The pool caps at 100 active connections by default. Set SSH_MCP_MAX_POOL_SIZE=<n> to raise it for fan-out workloads against many distinct hosts (e.g. ssh_multi_exec across a large fleet). When the cap is reached, the pool evicts an idle entry to make room; if every entry is in use it rejects with Connection pool is full.
SSH config support
All connections respect your ~/.ssh/config. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have Host myserver configured in your SSH config, just pass host: "myserver" — ssh-mcp resolves everything.
ProxyJump / bastion hosts are supported automatically. If your SSH config has ProxyJump bastion for a host, ssh-mcp connects through the bastion transparently. Chained proxies work too.
Host key verification
All remote operations verify the server's host key against ~/.ssh/known_hosts:
Known host, key matches — accept.
Known host, key changed — reject (MITM protection).
Unknown host — accept on first connection (TOFU). Use
ssh_known_hosts_fixto pin the key for future mismatch detection.
For stricter environments, set SSH_MCP_STRICT_HOST_KEY=1 to reject unknown hosts. Add them explicitly with ssh_known_hosts_fix first.
The diagnostic tools (ssh_test, ssh_diagnose) use StrictHostKeyChecking=no for their probe commands. Those probes only run echo SSH_OK — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the hostVerifier.
Command policy
ssh_exec and ssh_multi_exec accept free-form shell commands from the agent. For security-conscious deployments, you can restrict which commands run via two env vars, each accepting a comma-separated list of regex patterns:
SSH_MCP_COMMAND_WHITELIST— if set, the command must match at least one pattern, else it's blocked.SSH_MCP_COMMAND_BLACKLIST— if set, the command must not match any pattern, else it's blocked.
When both are set, the command must pass both checks (whitelist first, then blacklist). When neither is set (the default), all commands are allowed.
Patterns are JavaScript regexes. Use ^ and $ for anchored matches; otherwise patterns are treated as substring matches. Commas are the delimiter, so a literal comma in a pattern needs to be expressed as \x2c or via a character class.
# Read-only allowlist: only ls / df / cat / find / tail
SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "
# Block destructive ops even if your agent goes off-script
SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"Blocked commands surface as a clear error mentioning which pattern (or which env var) rejected the call, so the agent can adapt rather than guess. Policy is enforced before the SSH connection opens — no remote process is started for a blocked command.
The structured higher-level tools (ssh_find, ssh_tail, ssh_service_status, SFTP ops) are exempt from policy. They build commands from typed parameters, so a tight ^ls whitelist would otherwise force you to allow ^find , ^tail , ^systemctl just to keep those tools working — defeating the point of a tight whitelist.
Policy interaction with ssh_exec's env parameter
When ssh_exec is called with env: { KEY: "value" }, the values are injected as a KEY='value' ... shell prefix before the command (see the ssh_exec description). Policy is checked against the full prefixed command, not the bare command argument. That's the safer ordering at the protocol layer — but it means whitelist patterns need to anticipate the prefix and must be anchored, not substring matches:
# WRONG -- blocks any ssh_exec call that uses `env`, because the final command
# starts with `KEY='value' ` and never matches `^ls`.
SSH_MCP_COMMAND_WHITELIST="^ls "
# RIGHT -- allow zero or more `KEY='value' ` prefixes before the real command.
SSH_MCP_COMMAND_WHITELIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*ls( |$)"Avoid substring-match patterns like ls if you're worried about a hostile agent. An agent could pass env: { ATTACK: " ls " } to make the final command ATTACK=' ls ' rm -rf /, which matches a substring ls and bypasses the whitelist. Anchored patterns of the form above don't have this weakness because they require the real command name to follow the env-prefix block, not appear inside a quoted env value.
Blacklists need the same care. ^rm blocks a bare rm call, but doesn't block FOO='bar' rm. Use the same env-prefix-tolerant anchor:
SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"If you don't trust the agent's env values at all, the simplest mitigation is to leave env unused in your client config and pass everything through the command string yourself.
Windows support
On Windows, ssh-mcp detects the OpenSSH Authentication Agent service automatically (via the \\.\pipe\openssh-ssh-agent named pipe). No SSH_AUTH_SOCK needed — just make sure the OpenSSH agent service is running.
The published npm command runs the bundled Node entrypoint directly for compatibility with restricted serverless MCP hosts such as ModelScope.
Authentication
All remote operations accept connection parameters:
Parameter | Description | Default |
| SSH hostname or IP (required) | — |
| SSH port | From SSH config or |
| SSH username | From SSH config or current user |
| Path to SSH private key | Auto-detect |
| Alias configured as a server-only | — |
Auth resolution order: ssh-mcp picks the first match from this list and does not fall through to later entries — this makes the auth method deterministic and predictable.
Explicit
privateKeyPathPassword resolved from
credential_idssh-agent (
SSH_AUTH_SOCKon Unix,\\.\pipe\openssh-ssh-agenton Windows)Identity files from
~/.ssh/configfor the hostDefault key paths (
~/.ssh/id_ed25519,id_rsa,id_ecdsa)
Real passwords are never MCP tool parameters. Configure one ordinary environment variable
per credential on the MCP server, then let the agent select host, port, username, and
credential_id dynamically. IDs are uppercased and non-alphanumeric characters become
underscores:
SSH_CREDENTIAL_SSH1=password1
SSH_CREDENTIAL_SSH2=password2
SSH_CREDENTIAL_ABC_TEST=password3{
"host": "bore.pub",
"port": 45201,
"username": "root",
"credential_id": "ssh1",
"command": "hostname"
}If credential_id is omitted, key and ssh-agent authentication continue to work. An unknown
alias fails without including any configured password in the error message.
For backward compatibility, SSH_CREDENTIALS_JSON remains available as a fallback. A matching
SSH_CREDENTIAL_<ID> variable always takes precedence, so platforms such as ModelScope do not
need to preserve or escape JSON environment-variable values.
Example workflows
Agent can't git pull
Agent calls ssh_git_check → "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list → finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") → "Key loaded"
Agent calls ssh_git_check → "Git SSH authentication to github.com succeeded as username"
Agent runs git pull → worksHost key changed after instance recreation
Agent calls ssh_exec on server → error: "Host key verification failed"
(auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") → "Host key refreshed"
Agent calls ssh_exec → worksFirst-time connection to a new server
Agent calls ssh_test("new-server") → "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") → full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"Programmatic usage
import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool } from '@txcxgzs/ssh-mcp';
// Fix SSH environment
const agent = ensureAgent();
console.log(agent.message);
// Check git access
const git = checkGitSsh('github.com');
console.log(git.message);
// List available keys
const keys = listSshKeys();
for (const key of keys) {
console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}
// Run a remote command (one-off)
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();
// Run multiple commands with connection pooling
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r1 = await exec(client, 'uptime');
console.log(r1.stdout);
});
// Connection stays open for 60s — next call reuses it
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r2 = await exec(client, 'df -h');
console.log(r2.stdout);
});
pool.drain(); // close all connections when done
// Diagnose issues
const report = diagnose('my-server');
console.log(report.overall); // "ok" | "warning" | "error"
for (const check of report.checks) {
console.log(`[${check.status}] ${check.name}: ${check.message}`);
}Requirements
Node.js 18+
SSH client installed (for diagnostics and environment management)
License
MIT
Available Tools
21 toolsssh_agent_ensureA
Ensure ssh-agent is running and reachable. Starts a new agent if needed and sets environment variables so subsequent SSH operations work. Use this FIRST when SSH operations fail with agent-related errors.
Inputs: no named parameters.
ssh_config_lookupA
Resolve the effective SSH configuration for a host. Shows hostname, user, port, identity files, proxy settings, and all other options from ~/.ssh/config. Use this to understand how SSH will connect to a host.
Inputs: host (required).
ssh_deleteA
Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with rm -rf explicitly so the destructive intent is visible in the tool trace.
Inputs: host (required), path (required), port, username, +2 more.
ssh_diagnoseA
Diagnose SSH connectivity issues. Checks ssh-agent status, loaded keys, known_hosts, SSH config, and attempts a test connection. Use this BEFORE attempting SSH operations if you suspect connectivity issues, or AFTER a failed SSH operation to understand why it failed.
Inputs: host (required), port.
ssh_downloadA
Download a file from a remote host to local filesystem via SFTP.
Inputs: host (required), localPath (required), remotePath (required), port, +3 more.
ssh_execA
Execute a command on a remote host via SSH. The command is interpreted by the remote login shell — pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use env to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).
Inputs: host (required), command (required), env, port, +4 more.
ssh_findB
Search for files on a remote host. Wraps the find command with structured parameters so you don't have to construct find syntax manually.
Inputs: host (required), path (required), name, port, +9 more.
ssh_git_checkA
Test Git-over-SSH authentication to a hosting provider (GitHub, GitLab, Bitbucket, etc). Verifies your SSH key is registered and working. Use this when git clone/pull/push fails with SSH errors.
Inputs: host, user.
ssh_key_listA
List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded.
Inputs: no named parameters.
ssh_key_loadA
Load an SSH private key into the running agent. Ensures the agent is running first. Use this after ssh_key_list shows a key that is not loaded.
Inputs: keyPath (required).
ssh_known_hosts_fixA
Remove a stale host key from known_hosts and re-scan the host to add the current key. Use this when you see 'Host key verification failed' errors, typically after a server has been recreated or reprovisioned.
Inputs: host (required), port.
ssh_lsB
List files in a directory on a remote host via SFTP.
Inputs: host (required), path (required), port, username, +2 more.
ssh_mkdirA
Create a directory on a remote host via SFTP. Set recursive: true to create parent directories as needed (like mkdir -p). Existing intermediate dirs are tolerated; an existing leaf path is still an error.
Inputs: host (required), path (required), port, username, +3 more.
ssh_multi_execA
Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times — it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).
Inputs: hosts (required), command (required), port, timeout, +3 more.
ssh_read_fileB
Read a file from a remote host via SFTP.
Inputs: host (required), path (required), port, username, +2 more.
ssh_service_statusA
Check the status of a systemd service on a remote host. Returns whether it's active, its PID, uptime, and description. Use this instead of ssh_exec with systemctl.
Inputs: host (required), service (required), port, timeout, +3 more.
ssh_statA
Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and type flags (isFile, isDirectory, isSymbolicLink). Use this instead of parsing ls -la output.
Inputs: host (required), path (required), port, username, +2 more.
ssh_tailA
Read the last N lines of a file on a remote host, optionally filtering by a grep pattern. Use this for reading log files instead of ssh_exec with manual tail/grep commands.
Inputs: host (required), path (required), grep, port, +5 more.
ssh_testA
Quick connectivity test to an SSH host. Reports success/failure with timing and actionable error details. Lighter and faster than ssh_diagnose — use this for a quick check before running operations.
Inputs: host (required), port.
ssh_uploadB
Upload a local file to a remote host via SFTP.
Inputs: host (required), localPath (required), remotePath (required), port, +3 more.
ssh_write_fileA
Write content to a file on a remote host via SFTP. Creates or overwrites the file.
Inputs: host (required), path (required), content (required), port, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Every tool has a clearly defined purpose: execution, file transfer, metadata, diagnostics, key/agent management, and specialized helpers like git_check and service_status. Potential overlaps (e.g., ssh_test vs ssh_diagnose) are explicitly differentiated by speed and depth.
All tools share the ssh_ prefix and mostly follow a verb-noun pattern (ssh_read_file, ssh_write_file, ssh_upload, ssh_mkdir). A few deviate slightly, like ssh_known_hosts_fix and ssh_service_status, but the overall convention remains predictable.
21 tools is somewhat high for most servers, but the SSH domain genuinely spans execution, SFTP, key management, agent management, diagnostics, and networking. Each tool appears to justify its inclusion, though a few edge-case utilities feel additive.
The toolset covers the core lifecycle of SSH operations: connection, command exec, file transfer, diagnostics, key loading, and service status checking. Minor gaps exist, such as no remote file move/rename or permission change tool, but these are likely outside the primary scope because ssh_exec can handle them.
Maintenance
Related MCP Connectors
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Manage servers through SSH.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to securely connect to and manage remote servers via SSH, supporting command execution, file transfers via SFTP, and multi-server management with both password and SSH key authentication.953 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to execute commands and transfer files on remote servers over SSH connections.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely execute commands, transfer files, and manage port forwarding on remote servers via SSH.164 npm38Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to establish and manage persistent SSH sessions, supporting smart command execution, async tasks, multi-host, sudo, and file operations through SFTP.1565 PyPIMIT