MCP SSH Agent

一个用于管理和控制SSH连接的模型上下文协议（MCP）服务器。该服务器与Claude Desktop和其他兼容MCP的客户端无缝集成，提供AI驱动的SSH操作。

概览

此MCP服务器通过干净、标准化的接口提供SSH操作，可以被兼容MCP的语言模型如Claude Desktop使用。服务器会自动从你的~/.ssh/config和~/.ssh/known_hosts文件中发现SSH主机，并使用原生SSH工具执行命令以确保最大可靠性。

快速开始

桌面扩展安装（推荐）

最简单的安装MCP SSH Agent的方法是通过桌面扩展（.dxt）格式：

1. 从GitHub发布页面下载最新的mcp-ssh-*.dxt文件。
2. 双击.dxt文件将其安装到Claude Desktop中。
3. SSH工具将在你与Claude的对话中自动可用。

其他安装方法

通过npx安装

npx @aiondadotcom/mcp-ssh

手动配置Claude Desktop

要使用手动配置将此MCP服务器与Claude Desktop结合使用，请在你的MCP设置文件中添加以下内容：

在macOS上：~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

添加此配置后，重启Claude Desktop。SSH工具将在你与Claude的对话中可用。

全局安装

npm install -g @aiondadotcom/mcp-ssh

本地开发

git clone https://github.com/aiondadotcom/mcp-ssh.git
cd mcp-ssh
npm install
npm start

示例用法

上图显示了MCP SSH Agent的实际运行情况，展示了它如何与兼容MCP的客户端集成，提供无缝的SSH操作。

与Claude的集成

此截图演示了MCP SSH Agent与Claude的集成，展示了AI助手如何直接管理SSH连接并通过MCP协议执行远程命令。

主要特性

• 可靠的SSH：使用原生ssh/scp命令而不是JavaScript SSH库
• 自动发现：从SSH配置和已知主机文件中查找主机
• 完整的SSH支持：支持SSH代理、密钥和所有身份验证方法
• 文件操作：使用scp上传和下载文件
• 批处理命令：顺序执行多个命令
• 错误处理：全面的错误报告和超时处理

功能

代理提供了以下MCP工具：

1. listKnownHosts() - 列出所有已知的SSH主机，优先列出来自~/.ssh/config的条目，然后是来自~/.ssh/known_hosts的额外主机
2. runRemoteCommand(hostAlias, command) - 使用ssh在远程主机上执行命令
3. getHostInfo(hostAlias) - 返回特定主机的详细配置
4. checkConnectivity(hostAlias) - 测试到主机的SSH连接性
5. uploadFile(hostAlias, localPath, remotePath) - 使用scp将文件上传到远程主机
6. downloadFile(hostAlias, remotePath, localPath) - 使用scp从远程主机下载文件
7. runCommandBatch(hostAlias, commands) - 顺序执行多个命令

配置示例

Claude Desktop集成

这里是如何配置你的Claude Desktop：

{
  "mcpServers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

手动服务器配置

如果你希望手动运行服务器或将其与其他MCP客户端集成：

{
  "servers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

要求

• Node.js 18或更高版本
• 已安装的SSH客户端（ssh和scp命令可用）
• SSH配置文件（~/.ssh/config和~/.ssh/known_hosts）

使用Claude Desktop

配置完成后，你可以请求Claude帮助你进行SSH操作，例如：

• “列出我所有的SSH主机”
• “检查生产服务器的连接性”
• “在我的Web服务器上运行一个命令”
• “将这个文件上传到我的远程服务器”
• “从我的应用服务器下载日志”

Claude将使用MCP SSH工具安全高效地执行这些操作。

使用

代理作为Model Context Protocol服务器通过STDIO运行。通过npm安装后，可以直接使用：

# 通过npx运行（推荐）
npx @aiondadotcom/mcp-ssh

# 或者如果全局安装
mcp-ssh

# 开发使用 - 带调试输出
npm start

服务器通过STDIO上的干净JSON进行通信，使其非常适合像Claude Desktop这样的MCP客户端。

高级配置

环境变量

• MCP_SILENT=true - 禁用调试输出（当作为MCP服务器使用时自动设置）

SSH配置

代理读取标准SSH配置文件：

• ~/.ssh/config - SSH客户端配置（支持Include指令）
• ~/.ssh/known_hosts - 已知主机密钥

确保你的SSH密钥正确配置并可通过SSH代理或密钥文件访问。

Include指令支持

MCP SSH Agent完全支持SSH Include指令来组织你的配置跨越多个文件。但是，需要注意一个重要的SSH错误：

⚠️ SSH Include指令错误警告

SSH有一个配置解析错误，其中Include语句必须放在你的~/.ssh/config文件的开头才能正常工作。如果放在末尾，SSH会读取它们但不会正确应用包含的配置。

✅ 正确放置（在开头）：

# ~/.ssh/config
Include ~/.ssh/config.d/*
Include ~/.ssh/work-hosts

# 全局设置
ServerAliveInterval 55

# 主机定义
Host myserver
    HostName example.com

❌ 错误放置（在末尾） - 不会工作：

# ~/.ssh/config
# 全局设置
ServerAliveInterval 55

# 主机定义
Host myserver
    HostName example.com

# 这些Include语句由于SSH错误而无法正常工作：
Include ~/.ssh/config.d/*
Include ~/.ssh/work-hosts

MCP SSH Agent无论其在文件中的位置如何都会正确处理Include指令，因此即使SSH本身有问题，你也会得到完整的主机发现。

示例 ~/.ssh/config

这是一个示例SSH配置文件，展示了各种连接场景，包括Include指令：

# Include指令必须放在开头，因为SSH错误
Include ~/.ssh/config.d/*
Include ~/.ssh/work-servers

# 全局设置 - 保持连接活跃
ServerAliveInterval 55

# 通过跳板主机访问的生产服务器
Host prod
    Hostname 203.0.113.10
    Port 22022
    User deploy
    IdentityFile ~/.ssh/id_prod_rsa

# 生产服务器的root访问（单独条目）
Host root@prod
    Hostname 203.0.113.10
    Port 22022
    User root
    IdentityFile ~/.ssh/id_prod_rsa

# 通过生产跳板主机访问的归档服务器
Host archive
    Hostname 2001:db8:1f0:cafe::1
    Port 22077
    User archive-user
    ProxyJump prod

# 具有特定配置的Web服务器
Host web1.example.com
    Hostname 198.51.100.15
    Port 22022
    User root
    IdentityFile ~/.ssh/id_ed25519

Host web2.example.com
    Hostname 198.51.100.25
    Port 22022
    User root
    IdentityFile ~/.ssh/id_ed25519

# 具有自定义密钥的数据库服务器
Host database
    Hostname 203.0.113.50
    Port 22077
    User dbadmin
    IdentityFile ~/.ssh/id_database_rsa
    IdentitiesOnly yes

# 邮件服务器
Host mail1
    Hostname 198.51.100.88
    Port 22078
    User mailuser

Host root@mail1
    Hostname 198.51.100.88
    Port 22078
    User root

# 监控服务器
Host monitor
    Hostname 203.0.113.100
    Port 22077
    User monitoring
    IdentityFile ~/.ssh/id_monitor_ed25519
    IdentitiesOnly yes

# 负载均衡器
Host lb-a
    Hostname 198.51.100.200
    Port 22077
    User root

Host lb-b
    Hostname 198.51.100.201
    Port 22077
    User root

此配置展示了：

• 全局设置：ServerAliveInterval以保持连接活跃
• 自定义端口：非标准SSH端口以提高安全性
• 多个用户：同一主机的不同用户账户（例如，prod和root@prod）
• 跳板主机：使用ProxyJump通过堡垒主机访问服务器
• IPv6地址：现代网络支持
• 身份文件：不同服务器的特定SSH密钥
• 安全选项：IdentitiesOnly yes仅使用指定的密钥

MCP SSH Agent如何使用你的配置

MCP SSH Agent会自动发现并使用你的SSH配置：

1. 主机发现：来自~/.ssh/config的所有主机都自动可用
2. 原生SSH：使用系统中的ssh命令，所以所有配置选项都能工作
3. 身份验证：尊重你的SSH代理、密钥文件和身份验证设置
4. 跳板主机：支持复杂的代理链和堡垒主机设置
5. 端口转发：可以与自定义端口和连接选项一起工作

与Claude Desktop的示例用法：

• “列出我的SSH主机” → 显示所有配置的主机，包括prod、archive、web1.example.com等
• “连接到归档服务器” → 自动使用ProxyJump配置
• “在web1.example.com上运行'df -h'” → 使用正确的用户、端口和密钥连接
• “将文件上传到数据库服务器” → 使用特定的身份文件和端口配置

故障排除

常见问题

1. 找不到命令：确保ssh和scp已安装并在PATH中
2. 权限被拒绝：检查SSH密钥权限和SSH代理
3. 主机未找到：验证主机是否存在于~/.ssh/config或~/.ssh/known_hosts中
4. 连接超时：检查网络连接和防火墙设置

调试模式

启用调试输出以查看详细的操作日志：

# 启用调试模式
MCP_SILENT=false npx @aiondadotcom/mcp-ssh

SSH密钥设置指南

为了让MCP SSH Agent正常工作，你需要设置SSH密钥认证。这里是一个完整的指南：

1. 创建SSH密钥

生成新的SSH密钥对（建议使用Ed25519以获得更好的安全性）：

# 生成Ed25519密钥（推荐）
ssh-keygen -t ed25519 -C "your-email@example.com"

# 或生成RSA密钥（如果Ed25519不被支持）
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

重要：当提示输入密码短语时，留空（按Enter）。MCP SSH Agent不能处理带有密码保护的密钥，因为它是非交互式运行的。

输入密码短语（留空表示无密码短语）：[按Enter]
再次输入相同的密码短语：[按Enter]

这将创建两个文件：

• ~/.ssh/id_ed25519（私钥） - 保密！
• ~/.ssh/id_ed25519.pub（公钥） - 将此复制到服务器

2. 在远程服务器上安装公钥

将你的公钥复制到远程服务器的authorized_keys文件中：

# 方法1：使用ssh-copy-id（最简单）
ssh-copy-id user@hostname

# 方法2：手动复制
cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

# 方法3：手动复制和粘贴
cat ~/.ssh/id_ed25519.pub
# 然后SSH到服务器并将内容粘贴到~/.ssh/authorized_keys

3. 服务器端SSH配置

为了在你的SSH服务器上启用仅密钥认证，编辑/etc/ssh/sshd_config：

# 编辑SSH守护进程配置
sudo nano /etc/ssh/sshd_config

添加或修改以下设置：

# 启用公钥认证
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

# 禁用密码认证（最佳安全实践）
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

# 根登录选项（选择一个）：
# 选项1：允许仅使用SSH密钥的根登录（推荐用于管理员访问）
PermitRootLogin prohibit-password

# 选项2：完全禁用根登录（最安全，但灵活性较低）
# PermitRootLogin no

# 可选：限制SSH访问特定用户
AllowUsers deploy root admin

# 可选：更改默认端口以提高安全性
Port 22022

编辑后，重启SSH服务：

# 在Ubuntu/Debian上
sudo systemctl restart ssh

# 在CentOS/RHEL/Fedora上
sudo systemctl restart sshd

# 在macOS上
sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist
sudo launchctl load /System/Library/LaunchDaemons/ssh.plist

4. 设置正确的权限

SSH对文件权限非常严格。正确设置它们：

在你的本地机器上：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

在远程服务器上：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

5. 测试SSH密钥认证

在使用MCP SSH Agent之前测试你的连接：

# 测试连接
ssh -i ~/.ssh/id_ed25519 user@hostname

# 测试带调试输出的连接
ssh -v -i ~/.ssh/id_ed25519 user@hostname

# 测试特定配置
ssh -F ~/.ssh/config hostname

6. 不同服务器的不同密钥

你可以为不同的服务器创建不同的密钥：

# 创建特定密钥
ssh-keygen -t ed25519 -f ~/.ssh/id_production -C "production-server"
ssh-keygen -t ed25519 -f ~/.ssh/id_staging -C "staging-server"

然后在~/.ssh/config中配置它们：

Host production
    Hostname prod.example.com
    User deploy
    IdentityFile ~/.ssh/id_production
    IdentitiesOnly yes

Host staging
    Hostname staging.example.com
    User deploy
    IdentityFile ~/.ssh/id_staging
    IdentitiesOnly yes

安全最佳实践

SSH密钥安全

• 永远不要使用带有密码保护的密钥与MCP SSH Agent
• 永远不要分享私钥 - 它们应该只保留在你的机器上
• 尽可能使用Ed25519密钥（比RSA更安全）
• 为不同的环境/目的创建独立的密钥
• 定期轮换密钥（每6-12个月）

服务器安全

• 完全禁用密码认证
• 使用非标准SSH端口以减少自动化攻击
• 限制SSH访问到特定用户使用AllowUsers
• 选择适当的root登录策略：
  • PermitRootLogin prohibit-password - 允许仅使用SSH密钥的root访问（推荐用于管理任务）
  • PermitRootLogin no - 完全禁用root登录（最安全，但需要sudo访问）
• 为所有账户启用SSH密钥认证
• 考虑使用跳板主机以增加安全层

网络安全

• 使用VPN或堡垒主机为生产服务器
• 实施fail2ban以阻止暴力尝试
• 定期监控SSH日志
• 谨慎使用SSH密钥转发（不需要时禁用）

构建桌面扩展

对于希望本地构建DXT包的开发者：

先决条件

• Node.js 18或更高