@yawlabs/ssh-mcp

Name: SSH MCP Server
Author: YawLabs

npm version License: MIT

面向 AI 智能体的 SSH 操作。 这是一个 MCP 服务器，提供远程命令执行、文件传输以及内置的 SSH 诊断功能，能准确告知你哪里出了问题以及如何修复。

由 Yaw Labs 构建和维护。

为什么选择这个工具？

AI 智能体在通过 SSH 连接远程服务器时总是遇到同样的问题：ssh-agent 挂掉、加载了错误的密钥、重建实例导致的主机密钥过期、权限被拒绝且没有有用的上下文信息。大多数 SSH MCP 服务器只是简单地封装了 ssh2，让智能体自己去处理那些晦涩难懂的错误。

本工具内置了 ssh_diagnose —— 一个诊断工具，用于检查你的整个 SSH 环境（代理、密钥、配置、known_hosts、连通性）并返回可执行的修复命令。在连接前或连接失败后使用它。

快速开始

npm install -g @yawlabs/ssh-mcp

添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-mcp"
    }
  }
}

工具

核心操作

工具	描述
`ssh_exec`	在远程主机上执行命令。返回 stdout、stderr 和退出代码。
`ssh_read_file`	通过 SFTP 从远程主机读取文件。
`ssh_write_file`	通过 SFTP 将内容写入远程主机的文件。
`ssh_upload`	通过 SFTP 将本地文件上传到远程主机。
`ssh_download`	将文件从远程主机下载到本地文件系统。
`ssh_ls`	列出远程主机目录中的文件。

诊断

工具	描述
`ssh_diagnose`	诊断 SSH 连接问题。检查代理、密钥、known_hosts、SSH 配置和实时连通性。返回可执行的修复命令。

身份验证

所有工具都接受连接参数：

参数	描述	默认值
`host`	SSH 主机名或 IP（必填）	—
`port`	SSH 端口	`22`
`username`	SSH 用户名	当前用户
`privateKeyPath`	SSH 私钥路径	自动检测
`password`	SSH 密码（建议使用密钥）	—

身份验证解析顺序： 显式密钥 > 显式密码 > ssh-agent (SSH_AUTH_SOCK) > 默认密钥路径 (~/.ssh/id_ed25519, id_rsa, id_ecdsa)。

诊断

ssh_diagnose 运行 5 项检查并返回结构化报告：

SSH 代理 — ssh-agent 是否在运行？是否加载了密钥？
SSH 密钥 — ~/.ssh/ 中是否存在私钥？
SSH 配置 — 该主机是否有配置条目？（支持通配符）
已知主机 (Known Hosts) — 主机密钥是否已缓存？
连通性 — 我们是否真的能连接上？

每项失败的检查都包含修复它的确切命令。输出示例：

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

编程使用

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}`);
}

要求

Node.js 18+
已安装 SSH 客户端（用于诊断）

许可证

MIT

Install Server

A

security – no known vulnerabilities

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

SSH MCP Server