MCP Ssh Manager

🚀 MCP SSH 管理器

MCP SSH 管理器是一款強大的 Model Context Protocol (MCP) 服務器，它能讓 Claude Code 無縫管理多個 SSH 連接。用戶可以直接在 Claude Code 中控制遠程服務器、執行命令以及傳輸文件。

🚀 快速開始

1. 克隆倉庫

git clone https://github.com/yourusername/mcp-ssh-manager.git
cd mcp-ssh-manager

2. 安裝依賴

npm install
pip install -r tools/requirements.txt

3. 配置服務器

運行交互式配置工具：

python tools/server_manager.py

選擇選項 2 來添加服務器。你需要提供以下信息：

• 服務器名稱（例如，production、staging）
• 主機/IP 地址
• 用戶名
• 端口（默認：22）
• 認證方式（密碼或 SSH 密鑰）

4. 安裝到 Claude Code

# 個人使用（僅當前用戶）
claude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js

# 團隊共享（在項目中創建 .mcp.json）
claude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js

# 所有項目使用
claude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js

5. 開始使用！

在 Claude Code 中，你現在可以執行以下操作：

"List all my SSH servers"
"Execute 'ls -la' on production server"  # 如果設置了默認目錄，則使用默認目錄
"Run 'docker ps' on staging"
"Upload config.json to production:/etc/app/config.json"
"Download logs from staging:/var/log/app.log"

使用默認目錄： 如果你將 /var/www/html 設置為生產服務器的默認目錄，以下命令是等效的：

• "Run 'ls' on production" → 在 /var/www/html 中執行
• "Run 'ls' on production in /tmp" → 在 /tmp 中執行（覆蓋默認目錄）

✨ 主要特性

• 🔗 多 SSH 連接 - 可從單個界面管理無限數量的 SSH 服務器
• 🔐 安全認證 - 支持密碼和 SSH 密鑰兩種認證方式
• 📁 文件操作 - 在本地和遠程系統之間上傳和下載文件
• ⚡ 命令執行 - 在遠程服務器上運行命令，並支持工作目錄
• 📂 默認目錄 - 為每個服務器設置默認工作目錄，方便使用
• 🎯 輕鬆配置 - 通過 .env 文件和引導式配置工具進行簡單設置
• 🔧 連接測試 - 內置工具可驗證服務器連接性
• 🚀 智能部署 - 新增！自動處理文件部署和權限問題
• 🔑 sudo 支持 - 新增！安全地以 sudo 權限執行命令
• 🏷️ 服務器別名 - 新增！使用短別名代替完整的服務器名稱

📦 安裝指南

先決條件

• Node.js（v16 或更高版本）
• Python 3.8+
• 安裝 Claude Code CLI
• npm（隨 Node.js 一起安裝）

💻 使用示例

基礎用法

在 Claude Code 中執行命令的基礎示例：

"List all my SSH servers"

高級用法

使用高級工具進行文件部署和以 sudo 權限執行命令：

# 使用 ssh_deploy 工具部署文件
"ssh_deploy production ['config.json'] {'owner': 'root', 'permissions': '644', 'backup': true, 'restart': false}"

# 使用 ssh_execute_sudo 工具以 sudo 權限執行命令
"ssh_execute_sudo production 'apt update' 'sudo_password' '/tmp'"

📚 詳細文檔

可用的 MCP 工具

核心工具

• ssh_list_servers：列出所有配置的 SSH 服務器及其詳細信息。
• ssh_execute：在遠程服務器上執行命令。
  • 參數：server（名稱）、command、cwd（可選工作目錄）
  • 注意：如果未提供 cwd，則使用服務器的默認目錄（如果已配置）
• ssh_upload：將文件上傳到遠程服務器。
  • 參數：server、local_path、remote_path
• ssh_download：從遠程服務器下載文件。
  • 參數：server、remote_path、local_path

高級工具（v1.2+）

• ssh_deploy 🚀：自動處理文件部署的權限和備份。
  • 參數：server、files（數組）、options（所有者、權限、備份、重啟）
  • 自動處理權限問題並創建備份
• ssh_execute_sudo 🔐：以 sudo 權限執行命令。
  • 參數：server、command、password（可選）、cwd（可選）
  • 安全處理 sudo 密碼，不會在日誌中暴露
• ssh_alias 🏷️：管理服務器別名，方便訪問。
  • 參數：action（添加/刪除/列出）、alias、server
  • 示例：為 "production" 服務器創建別名 "prod"
• ssh_command_alias 📝：管理常用命令的別名。
  • 參數：action（添加/刪除/列出/建議）、alias、command
  • 別名從活動配置文件加載
  • 示例：為項目自定義別名
• ssh_hooks 🎣：管理 SSH 操作的自動化鉤子。
  • 參數：action（列出/啟用/禁用/狀態）、hook
  • 鉤子從活動配置文件加載
  • 示例：項目特定的驗證和自動化
• ssh_profile 📚：管理不同項目類型的配置文件。
  • 參數：action（列出/切換/當前）、profile
  • 可用配置文件：默認、frappe、docker、nodejs
  • 示例：在不同項目配置之間切換

配置

配置文件

SSH 管理器使用配置文件為不同項目類型配置別名和鉤子：

1. 設置活動配置文件：

• 環境變量：export SSH_MANAGER_PROFILE=frappe
• 配置文件：創建 .ssh-manager-profile 文件並指定配置文件名稱
• 默認：如果未指定，則使用 default 配置文件

2. 可用配置文件：

• default - 基本 SSH 操作
• frappe - 特定於 Frappe/ERPNext
• docker - Docker 容器管理
• nodejs - Node.js 應用程序
• 可在 profiles/ 目錄中創建自定義配置文件

環境變量

服務器在 .env 文件中按以下模式進行配置：

# 服務器配置模式
SSH_SERVER_[NAME]_HOST=hostname_or_ip
SSH_SERVER_[NAME]_USER=username
SSH_SERVER_[NAME]_PASSWORD=password  # 用於密碼認證
SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key  # 用於 SSH 密鑰認證
SSH_SERVER_[NAME]_PORT=22  # 可選，默認為 22
SSH_SERVER_[NAME]_DEFAULT_DIR=/path/to/dir  # 可選，默認工作目錄
SSH_SERVER_[NAME]_DESCRIPTION=Description  # 可選

# 示例
SSH_SERVER_PRODUCTION_HOST=prod.example.com
SSH_SERVER_PRODUCTION_USER=admin
SSH_SERVER_PRODUCTION_PASSWORD=secure_password
SSH_SERVER_PRODUCTION_PORT=22
SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/html
SSH_SERVER_PRODUCTION_DESCRIPTION=Production Server
SSH_SERVER_PRODUCTION_SUDO_PASSWORD=secure_sudo_pass  # 可選，用於自動部署

服務器管理工具

Python 管理工具 (tools/server_manager.py) 提供以下功能：

1. 列出服務器 - 查看所有已配置的服務器
2. 添加服務器 - 交互式服務器配置
3. 測試連接 - 驗證服務器連接性
4. 刪除服務器 - 刪除服務器配置
5. 更新 Claude Code - 在 Claude Code 中配置 MCP
6. 安裝依賴 - 設置所需的軟件包

項目結構

mcp-ssh-manager/
├── src/
│   └── index.js           # 主要的 MCP 服務器實現
├── tools/
│   ├── server_manager.py  # 交互式服務器管理
│   ├── test-connection.py # 連接測試工具
│   └── requirements.txt   # Python 依賴項
├── examples/
│   ├── .env.example       # 示例配置
│   └── claude-code-config.example.json
├── package.json           # Node.js 依賴項
├── .env                   # 你的服務器配置（從 .env.example 創建）
└── README.md             # 本文件

測試

測試服務器連接

python tools/test-connection.py production

驗證 MCP 安裝

claude mcp list

在 Claude Code 中檢查服務器狀態

/mcp

高級用法

文檔

• DEPLOYMENT_GUIDE.md - 部署策略和權限處理
• ALIASES_AND_HOOKS.md - 命令別名和自動化鉤子
• 實際示例和最佳實踐

故障排除

MCP 工具不可用

1. 確保已安裝 MCP：claude mcp list
2. 安裝後重啟 Claude Code
3. 檢查服務器日誌中的錯誤

連接失敗

1. 測試連接：python tools/test-connection.py [server_name]
2. 驗證網絡連接
3. 檢查防火牆規則
4. 確保遠程服務器上的 SSH 服務正在運行

權限被拒絕

1. 驗證用戶名和密碼/密鑰
2. 檢查 SSH 密鑰權限：chmod 600 ~/.ssh/your_key
3. 確保用戶在遠程服務器上具有必要的權限

貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 瞭解詳細信息。

開發設置

1. 分叉倉庫
2. 克隆並安裝依賴項
3. 設置預提交鉤子 以保證代碼質量：

./scripts/setup-hooks.sh

4. 創建你的功能分支
5. 進行更改（提交時鉤子將進行驗證）
6. 推送到你的分支
7. 打開拉取請求

代碼質量

本項目使用自動化質量檢查：

• ESLint 用於 JavaScript 代碼檢查
• Black 用於 Python 代碼格式化
• Flake8 用於 Python 代碼檢查
• Prettier 用於代碼格式化
• 預提交鉤子 用於自動驗證
• 密鑰檢測 以防止憑證洩露 手動運行驗證：./scripts/validate.sh

🔧 技術細節

安全最佳實踐

1. 切勿提交 .env 文件 - 始終使用 .env.example 作為模板
2. 儘可能使用 SSH 密鑰 - 比密碼更安全
3. 限制服務器訪問 - 使用最小必要權限
4. 定期輪換憑證 - 定期更新密碼和密鑰

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🙏 致謝

• 為 Claude Code 構建
• 使用 Model Context Protocol
• 通過 node-ssh 處理 SSH
• 使用 Paramiko 進行服務器管理

📧 支持

如有問題、疑問或建議：

• 在 GitHub Issues 上打開問題
• 在創建新問題之前檢查現有問題

為 Claude Code 社區精心打造 ❤️