MCP 服务器

SSH MCP Server

Enables secure remote command execution and file operations over SSH/SFTP with automatic authentication resolution. Features built-in diagnostics that identify connection issues—such as stale host keys, unloaded agents, or permission errors—and provide specific commands to fix them.

README

@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-agent running? 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}`);
}