@yawlabs/ssh-mcp
SSH operations for AI agents. MCP server with remote command execution, file transfer, and built-in SSH diagnostics that tell you exactly what's wrong and how to fix it.
Built and maintained by Yaw Labs.
Why this tool?
AI agents that SSH into remote servers hit the same problems over and over: dead ssh-agent, wrong key loaded, stale host keys from recreated instances, permission denied with no useful context. Most SSH MCP servers just wrap ssh2 and let the agent figure out cryptic errors.
This one includes ssh_diagnose — a diagnostic tool that checks your entire SSH environment (agent, keys, config, known_hosts, connectivity) and returns actionable fix commands. Use it before connecting or after a failure.
Quick start
npm install -g @yawlabs/ssh-mcp
Add to your MCP client config:
{
"mcpServers": {
"ssh": {
"command": "ssh-mcp"
}
}
}
Tools
Core operations
| Tool | Description |
|---|---|
ssh_exec | Execute a command on a remote host. Returns stdout, stderr, and exit code. |
ssh_read_file | Read a file from a remote host via SFTP. |
ssh_write_file | Write content to a file on a remote host via SFTP. |
ssh_upload | Upload a local file to a remote host via SFTP. |
ssh_download | Download a file from a remote host to local filesystem. |
ssh_ls | List files in a directory on a remote host. |
Diagnostics
| Tool | Description |
|---|---|
ssh_diagnose | Diagnose SSH connectivity issues. Checks agent, keys, known_hosts, SSH config, and live connectivity. Returns actionable fix commands. |
Authentication
All tools accept connection parameters:
| Parameter | Description | Default |
|---|---|---|
host | SSH hostname or IP (required) | — |
port | SSH port | 22 |
username | SSH username | Current user |
privateKeyPath | Path to SSH private key | Auto-detect |
password | SSH password (prefer keys) | — |
Auth resolution order: explicit key > explicit password > ssh-agent (SSH_AUTH_SOCK) > default key paths (~/.ssh/id_ed25519, id_rsa, id_ecdsa).
Diagnostics
ssh_diagnose runs 5 checks and returns a structured report:
- SSH Agent — Is
ssh-agentrunning? Are keys loaded? - SSH Keys — Do private keys exist in
~/.ssh/? - SSH Config — Is there a config entry for this host? (supports wildcards)
- Known Hosts — Is the host key cached?
- Connectivity — Can we actually connect?
Each failed check includes the exact command to fix it. Example output:
SSH Diagnostic Report for dev-server:22
Overall: ERROR
[PASS] SSH Agent
ssh-agent running with keys:
256 SHA256:abc... user@host (ED25519)
[PASS] SSH Keys
Found SSH keys: id_ed25519, gh_woods
[PASS] SSH Config
SSH config for "dev-server":
Host dev-server
HostName 10.0.1.50
User ec2-user
[FAIL] Known Hosts
Host "dev-server" is not in known_hosts.
[FAIL] Connectivity
Host key verification failed for dev-server. The host key changed (instance recreated?).
Suggested fixes:
- Remove stale host key: ssh-keygen -R "dev-server"
- Re-add host key: ssh-keyscan -H "dev-server" >> ~/.ssh/known_hosts
Programmatic usage
import { connect, exec, diagnose } from '@yawlabs/ssh-mcp';
// Run a command
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();
// Diagnose connectivity 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)
License
MIT