MCP Ssh

🚀 MCP SSH 代理

MCP SSH 代理是一個基於模型上下文協議（MCP）的服務器，用於管理和控制 SSH 連接。它能與 Claude Desktop 等支持 MCP 的客戶端無縫集成，為 SSH 操作提供強大的 AI 支持。

🚀 快速開始

📦 安裝指南

通過 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 集成

若要在 Claude Desktop 中使用此 MCP 服務器，需在 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 代理的實際運行情況，它與支持 MCP 的客戶端集成，實現了無縫的 SSH 操作。

與 Claude 集成

此截圖展示了 MCP SSH 代理與 Claude 的集成，AI 助手可通過 MCP 協議直接管理 SSH 連接並執行遠程命令。

與 Claude Desktop 配合使用

配置完成後，你可以向 Claude 提出以下 SSH 操作請求：

• “列出所有 SSH 主機”
• “檢查與生產服務器的連接”
• “在 Web 服務器上運行命令”
• “將文件上傳到遠程服務器”
• “從應用服務器下載日誌”

Claude 將使用 MCP SSH 工具安全高效地執行這些操作。

運行方式

該代理作為一個基於標準輸入輸出（STDIO）的模型上下文協議服務器運行。通過 npm 安裝後，可直接使用：

# 通過 npx 運行（推薦）
npx @aiondadotcom/mcp-ssh

# 若已全局安裝
mcp-ssh

# 開發環境 - 帶調試輸出運行
npm start

服務器通過標準輸入輸出以簡潔的 JSON 格式進行通信，非常適合 Claude Desktop 等 MCP 客戶端。

✨ 主要特性

• 可靠的 SSH 操作：使用原生的 ssh/scp 命令，而非 JavaScript SSH 庫，確保最大可靠性。
• 自動發現：從 ~/.ssh/config 和 ~/.ssh/known_hosts 文件中自動發現 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 集成配置

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

手動服務器配置

若要手動運行服務器或與其他 MCP 客戶端集成，可使用以下配置：

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

高級配置

環境變量

• MCP_SILENT=true：禁用調試輸出（作為 MCP 服務器使用時自動設置）。

SSH 配置

代理從標準 SSH 配置文件中讀取信息：

• ~/.ssh/config：SSH 客戶端配置
• ~/.ssh/known_hosts：已知主機密鑰

確保你的 SSH 密鑰已正確配置，並可通過 SSH 代理或密鑰文件訪問。

示例 ~/.ssh/config

# 全局設置 - 保持連接活躍
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. 端口轉發：可使用自定義端口和連接選項。

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"

重要提示：提示輸入密碼短語時，直接按回車鍵留空。因為 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：完全禁用根用戶登錄（最安全，但靈活性較低）
# 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

🔧 技術細節

要求

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

故障排除

常見問題

1. 命令未找到：確保 ssh 和 scp 已安裝並在系統路徑中。
2. 權限被拒絕：檢查 SSH 密鑰權限和 SSH 代理。
3. 主機未找到：驗證主機是否存在於 ~/.ssh/config 或 ~/.ssh/known_hosts 中。
4. 連接超時：檢查網絡連接和防火牆設置。

調試模式

帶調試輸出運行以查看詳細操作日誌：

# 啟用調試模式
MCP_SILENT=false npx @aiondadotcom/mcp-ssh

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

項目結構

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 配置

關於

本項目由 aionda.com 維護，通過模型上下文協議為 AI 助手和 SSH 基礎設施之間提供可靠的橋樑。

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

安全最佳實踐

SSH 密鑰安全

• 切勿使用受密碼保護的密鑰：MCP SSH 代理無法處理此類密鑰。
• 切勿共享私鑰：私鑰應僅保留在本地機器上。
• 優先使用 Ed25519 密鑰：比 RSA 更安全。
• 為不同環境/用途創建單獨的密鑰。
• 定期輪換密鑰：每 6 - 12 個月更換一次。

服務器安全

• 完全禁用密碼認證。
• 使用非標準 SSH 端口：減少自動化攻擊。
• 限制 SSH 訪問特定用戶：使用 AllowUsers 進行限制。
• 選擇合適的根用戶登錄策略：
  • PermitRootLogin prohibit-password：僅允許使用 SSH 密鑰進行根用戶登錄（推薦用於管理任務）。
  • PermitRootLogin no：完全禁用根用戶登錄（最安全，但需要 sudo 訪問權限）。
• 為所有賬戶啟用僅 SSH 密鑰認證。
• 考慮使用跳板主機：增加安全層。

網絡安全

• 為生產服務器使用 VPN 或跳板主機。
• 實施 fail2ban：阻止暴力破解嘗試。
• 定期監控 SSH 日誌。
• 謹慎使用 SSH 密鑰轉發：不需要時禁用。