MCP Ssh

🚀 MCP SSH代理

MCP SSH代理是一个基于模型上下文协议（MCP）的服务器，用于管理和控制SSH连接。它能够与Claude Desktop等支持MCP的客户端无缝集成，借助人工智能技术提供强大的SSH操作能力。

🚀 快速开始

📦 安装指南

通过npx安装（推荐）

npx @aiondadotcom/mcp-ssh

全局安装

npm install -g @aiondadotcom/mcp-ssh

本地开发

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

与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。在与Claude的对话中即可使用SSH工具。

💻 使用示例

基础用法

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

与Claude集成

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

✨ 主要特性

• 可靠的SSH操作：使用原生的ssh/scp命令，而非JavaScript SSH库，确保操作的可靠性。
• 自动发现：从SSH配置文件~/.ssh/config和~/.ssh/known_hosts中自动发现主机。
• 全面的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"]
    }
  }
}

使用说明

与Claude Desktop配合使用

配置完成后，您可以向Claude提出以下SSH操作请求：

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

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

一般使用方法

该代理作为一个通过标准输入输出（STDIO）通信的MCP服务器运行。通过npm安装后，您可以直接使用它：

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

# 或者全局安装后使用
mcp-ssh

# 开发时使用调试输出运行
npm start

服务器通过标准输入输出以简洁的JSON格式进行通信，非常适合Claude Desktop等MCP客户端。

高级配置

环境变量

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

SSH配置

该代理从标准的SSH配置文件中读取信息：

• ~/.ssh/config：SSH客户端配置
• ~/.ssh/known_hosts：已知主机密钥

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

示例~/.ssh/config

以下是一个示例SSH配置文件，展示了各种连接场景：

# 全局设置 - 保持连接活跃
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代理如何使用您的配置

MCP SSH代理会自动发现并使用您的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已安装并在您的系统路径中。
2. 权限被拒绝：检查SSH密钥权限和SSH代理。
3. 主机未找到：验证主机是否存在于~/.ssh/config或~/.ssh/known_hosts中。
4. 连接超时：检查网络连接性和防火墙设置。

调试模式

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

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

SSH密钥设置指南

为了使MCP SSH代理正常工作，您需要设置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代理以非交互式方式运行，无法处理受密码保护的密钥。

Enter passphrase (empty for no passphrase): [Press Enter]
Enter same passphrase again: [Press 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：完全禁用根用户登录（最安全，但需要sudo访问权限）
# 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代理之前，请测试您的连接：

# 测试连接
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代理配合使用。
• 切勿共享私钥 - 私钥应仅保留在您的机器上。
• 尽可能使用Ed25519密钥（比RSA更安全）。
• 为不同环境/目的创建单独的密钥。
• 定期轮换密钥（每6 - 12个月）。

服务器安全

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

网络安全

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

🔧 技术细节

项目结构

mcp-ssh/
├── server-simple.mjs          # 主要的MCP服务器实现
├── package.json               # 依赖项和脚本
├── README.md                  # 文档
├── LICENSE                    # MIT许可证
├── CHANGELOG.md               # 发布历史
├── PUBLISHING.md              # 发布说明
├── start.sh                   # 开发启动脚本
├── start-silent.sh            # 静默启动脚本
├── doc/
│   ├── example.png            # 使用示例截图
│   └── Claude.png             # Claude Desktop集成示例
├── src/                       # TypeScript源文件（开发用）
│   ├── ssh-client.ts          # SSH操作实现
│   ├── ssh-config-parser.ts   # SSH配置解析
│   └── types.ts               # 类型定义
└── tsconfig.json              # TypeScript配置

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

关于

本项目由 aionda.com 维护，通过模型上下文协议（MCP）为AI助手和SSH基础设施之间提供了可靠的桥梁。

贡献

欢迎贡献代码！请随时提交拉取请求。