⚙

SSH连接管理工具

MCP SSH Agent是一个通过Model Context Protocol（MCP）管理和控制SSH连接的服务器，与Claude Desktop等MCP兼容客户端无缝集成，提供AI驱动的SSH操作。

作者 By AiondaDotCom

本地部署 SSH管理远程命令执行

MCP SSH代理

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

概述

此MCP服务器通过一个干净、标准化的接口提供SSH操作，该接口可供MCP兼容的语言模型（如Claude Desktop）使用。服务器会自动从您的 ~/.ssh/config 和 ~/.ssh/known_hosts 使用本地SSH工具进行文件和执行命令，以获得最大的可靠性。

快速开始

桌面扩展安装（推荐）

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

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

替代安装方法

通过npx安装

BASH``` 1npx @aiondadotcom/mcp-ssh


#### 手动克劳德桌面配置


要使用手动配置将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到MCP设置文件中：


**在macOS上**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**在Windows上**: `%APPDATA%/Claude/claude_desktop_config.json`


JSON```
1
2
3
4
5
6
7
8{
  "mcpServers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

添加此配置后，重新启动Claude Desktop。SSH工具将可用于您与Claude的对话。

全球安装

BASH``` 1npm install -g @aiondadotcom/mcp-ssh


#### 本地开发


BASH```
1
2
3
4git clone https://github.com/aiondadotcom/mcp-ssh.git
cd mcp-ssh
npm install
npm start

示例用法

上面的屏幕截图显示了MCP SSH代理的运行情况，演示了它如何与MCP兼容的客户端集成，以提供无缝的SSH操作。

与Claude整合

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

主要特点

可靠的SSH：使用本地 ssh/scp 命令而不是JavaScript SSH库
自动发现：从SSH配置和known_hosts文件中查找主机
完全SSH支持：适用于SSH代理、密钥和所有身份验证方法
密码验证：支持基于密码的SSH登录和密钥密码 @password 注释——密码永远不会离开你的机器
文件操作：使用上传和下载文件 scp
批处理命令：按顺序执行多个命令
错误处理：具有超时功能的全面错误报告

函数

该代理提供以下MCP工具：

listKnownHosts（） -列出所有已知的SSH主机，优先考虑~/.SSH/config中的条目，然后是~/.SSH/known_hosts中的其他主机
runRemoteCommand（hostAlias，命令） -使用以下命令在远程主机上执行命令 ssh
getHostInfo（主机别名） -返回特定主机的详细配置
checkConnectivity（主机别名） -测试与主机的SSH连接
uploadFile（主机别名、本地路径、远程路径） -使用以下命令将文件上传到远程主机 scp
下载文件（hostAlias、remotePath、localPath） -使用从远程主机下载文件 scp
runCommandBatch（hostAlias，命令） -按顺序执行多个命令

配置示例

Claude桌面集成

以下是Claude Desktop配置的外观：

JSON``` 1 2 3 4 5 6 7 8{ “mcpServers”: { “mcp-ssh”: { “command”: “npx”, “args”: [“@aiondadotcom/mcp-ssh”] } } }


### 手动服务器配置


如果您更喜欢手动运行服务器或将其与其他MCP客户端集成：


JSON```
1
2
3
4
5
6
7
8{
  "servers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

需求

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

使用Claude Desktop

配置后，您可以要求Claude帮助您进行SSH操作，例如：

“列出我的所有SSH主机”
“检查与生产服务器的连接”
“在我的web服务器上运行命令”
“将此文件上载到我的远程服务器”
“从我的应用程序服务器下载日志”

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

用法

该代理作为STDIO上的模型上下文协议服务器运行。当通过npm安装时，你可以直接使用它：

BASH``` 1 2 3 4 5 6# Run via npx (recommended) npx @aiondadotcom/mcp-ssh

Or if installed globally

mcp-ssh

For development - run with debug output

npm start


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


## 高级配置


### 环境变量


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


### SSH配置


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


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


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


#### 密码验证


对于需要基于密码的身份验证的主机（常见于交换机和路由器等网络基础设施），您可以直接将密码存储在 `~/.ssh/config` 使用特殊注释：


SSH-CONFIG```
1
2
3
4
5
6
7
8
9Host myrouter
    HostName 192.168.1.1
    User admin
    # @password:yourSecretPassword
Host myserver
    HostName 10.0.0.5
    User deploy
    IdentityFile ~/.ssh/id_rsa
    # @password:myKeyPassphrase

它是如何工作的：

这 # @password: 注释已读取本地通过MCP服务器–密码从不到达AI模型或任何云提供商
适用于登录密码和SSH密钥密码
密码首先被拆分 :，因此密码包含 : 支持
列出主机时，仅 passwordAuth: true 显示-实际密码永远不会暴露

安全要求：

SSH配置文件必须有 600 使用时的权限 @password 注释
如果文件权限太开放，MCP服务器将拒绝启动
使用以下方式修复： chmod 600 ~/.ssh/config

包括指令支持

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

⚠️ SSH包含指令错误警告

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

✅ 正确的位置（在开头）：

SSH-CONFIG``` 1 2 3 4 5 6 7 8# ~/.ssh/config Include ~/.ssh/config.d/* Include ~/.ssh/work-hosts

Global settings

ServerAliveInterval 55

Host definitions

Host myserver HostName example.com


**❌ 位置不正确（在末尾）-不起作用：**


SSH-CONFIG```
1
2
3
4
5
6
7
8
9# ~/.ssh/config
# Global settings
ServerAliveInterval 55
# Host definitions
Host myserver
    HostName example.com
# These Include statements won't work properly due to SSH bug:
Include ~/.ssh/config.d/*
Include ~/.ssh/work-hosts

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

示例~/.ssh/config

这是一个示例SSH配置文件，演示了各种连接场景，包括Include指令和 @password 基于密码的身份验证注释：

SSH-CONFIG``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74# Include directives must be at the beginning due to SSH bug Include ~/.ssh/config.d/* Include ~/.ssh/work-servers

Global settings - keep connections alive

ServerAliveInterval 55

Production server with jump host

Host prod Hostname 203.0.113.10 Port 22022 User deploy IdentityFile ~/.ssh/id_prod_rsa

Root access to production (separate entry)

Host root@prod Hostname 203.0.113.10 Port 22022 User root IdentityFile ~/.ssh/id_prod_rsa

Router with password authentication (no SSH key)

Host router Hostname 192.168.1.1 User admin # @password:cQbG0q@019TAoehZel7V

Archive server accessed through production jump host

Host archive Hostname 2001:db8:1f0:cafe::1 Port 22077 User archive-user ProxyJump prod

Web servers with specific configurations

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

Database server with custom key and passphrase-protected key

Host database Hostname 203.0.113.50 Port 22077 User dbadmin IdentityFile ~/.ssh/id_database_rsa IdentitiesOnly yes # @password:U1Jqn=NoKdELYn&h1jVT

Mail servers (password auth, no SSH key)

Host mail1 Hostname 198.51.100.88 Port 22078 User mailuser # @password:7iBiV8lyoq*zANv46ALD Host root@mail1 Hostname 198.51.100.88 Port 22078 User root # @password:MRDHI2h!zhhN=ZJIxWzH

Monitoring server

Host monitor Hostname 203.0.113.100 Port 22077 User monitoring IdentityFile ~/.ssh/id_monitor_ed25519 IdentitiesOnly yes

Load balancers

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` 仅使用指定的密钥
- **密码认证**: `# @password:` 不支持SSH密钥的设备（如路由器、交换机）或密码保护密钥的注释


#### 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` 已安装并位于您的PATH中
2. **权限不足**：检查SSH密钥权限和SSH代理
3. **主机未找到**：验证主机是否存在于 `~/.ssh/config` 或 `~/.ssh/known_hosts`
4. **连接超时**：检查网络连接和防火墙设置


### 调试模式


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


BASH```
1
2# Enable debug mode
MCP_SILENT=false npx @aiondadotcom/mcp-ssh

SSH密钥设置指南

为了使MCP SSH代理正常工作，您需要设置SSH密钥身份验证。以下是一份完整的指南：

1.创建SSH密钥

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

BASH``` 1 2 3 4# Generate Ed25519 key (recommended) ssh-keygen -t ed25519 -C “your-email@example.com”

Or generate RSA key (if Ed25519 is not supported)

ssh-keygen -t rsa -b 4096 -C “your-email@example.com”


**重要**：当提示输入密码时， **留为空白** （按Enter键）。MCP SSH代理无法处理受密码保护的密钥，因为它以非交互方式运行。

1 2Enter passphrase (empty for no passphrase): [Press Enter] Enter same passphrase again: [Press Enter]


这将创建两个文件：


- `~/.ssh/id_ed25519` （私钥）-保守这个秘密！
- `~/.ssh/id_ed25519.pub` （公钥）-这将被复制到服务器


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


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


BASH```
1
2
3
4
5
6
7# Method 1: Using ssh-copy-id (easiest)
ssh-copy-id user@hostname
# Method 2: Manual copy
cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
# Method 3: Copy and paste manually
cat ~/.ssh/id_ed25519.pub
# Then SSH to the server and paste into ~/.ssh/authorized_keys

3.服务器端SSH配置

要在SSH服务器上启用仅使用安全密钥的身份验证，请编辑 /etc/ssh/sshd_config:

BASH``` 1 2# Edit SSH daemon configuration sudo nano /etc/ssh/sshd_config


添加或修改这些设置：


SSH-CONFIG```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# Enable public key authentication
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys
# Disable password authentication (security best practice)
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no
# Root login options (choose one):
# Option 1: Allow root login with SSH keys only (recommended for admin access)
PermitRootLogin prohibit-password
# Option 2: Completely disable root login (most secure, but less flexible)
# PermitRootLogin no
# Optional: Restrict SSH to specific users
AllowUsers deploy root admin
# Optional: Change default port for security
Port 22022

编辑后，重新启动SSH服务：

BASH``` 1 2 3 4 5 6 7# On Ubuntu/Debian sudo systemctl restart ssh

On CentOS/RHEL/Fedora

sudo systemctl restart sshd

On macOS

sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist sudo launchctl load /System/Library/LaunchDaemons/ssh.plist


### 4.设置正确的权限


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


**在您的本地计算机上：**


BASH```
1
2
3
4
5chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

在远程服务器上：

BASH``` 1 2chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys


### 5.测试SSH密钥认证


在使用MCP SSH代理之前测试您的连接：


BASH```
1
2
3
4
5
6# Test connection
ssh -i ~/.ssh/id_ed25519 user@hostname
# Test with verbose output for debugging
ssh -v -i ~/.ssh/id_ed25519 user@hostname
# Test specific configuration
ssh -F ~/.ssh/config hostname

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

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

BASH``` 1 2 3# Create specific keys ssh-keygen -t ed25519 -f ~/.ssh/id_production -C “production-server” ssh-keygen -t ed25519 -f ~/.ssh/id_staging -C “staging-server”


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


SSH-CONFIG```
1
2
3
4
5
6
7
8
9
10Host 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端口 减少自动攻击
限制SSH访问 对于特定用户 AllowUsers
选择适当的root登录策略:
PermitRootLogin prohibit-password -仅允许使用SSH密钥进行root访问（建议用于管理任务）
PermitRootLogin no -完全禁用root登录（最安全，但需要sudo访问）
启用仅SSH密钥身份验证 对于所有帐户
考虑使用跳转主机 用于附加安全层

网络安全

使用VPN或堡垒主机 用于生产服务器
机具故障2ban 阻止暴力企图
监视SSH日志 定期
谨慎使用SSH密钥转发 （不需要时禁用）

构建桌面扩展

对于希望在本地构建DXT包的开发人员：

先决条件

Node.js 20或更高版本
npm

构建DXT包

BASH``` 1 2 3 4# Install dependencies npm install

Build the DXT package

npm run build:dxt


这创建了一个 `.dxt` 文件在 `build/` 可以安装在Claude Desktop中的目录。


### 发布DXT版本


要发布新的DXT版本，请执行以下操作：


BASH```
1
2
3
4# Build the DXT package
npm run build:dxt
# Create a GitHub release with the DXT file
gh release create v1.0.3 build/mcp-ssh-1.0.3.dxt --title "Release v1.0.3" --notes "MCP SSH Agent v1.0.3"

DXT文件将作为发布资产供用户下载和安装。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16mcp-ssh/
├── server.mjs          # Main MCP server implementation
├── manifest.json              # DXT package manifest
├── package.json               # Dependencies and scripts
├── README.md                  # Documentation
├── LICENSE                    # MIT License
├── CHANGELOG.md               # Release history
├── PUBLISHING.md              # Publishing instructions
├── start.sh                   # Development startup script
├── start-silent.sh            # Silent startup script
├── scripts/
│   └── build-dxt.sh           # DXT package build script
├── doc/
│   ├── example.png            # Usage example screenshot
│   └── Claude.png             # Claude Desktop integration example
└── doc/                       # Documentation assets

关于

该项目由以下人员维护 aionda.com 并通过模型上下文协议在AI助手和SSH基础设施之间提供可靠的桥梁。