Ssh

🚀 SSH MCP Server

本項目提供一個可在本地運行的 MCP（Model Context Protocol）服務，藉助 SSH 實現對服務器的安全遠程操控，支持命令執行與文件傳輸（SFTP）。

🚀 快速開始

此項目提供本地運行的 MCP 服務，能通過 SSH 安全地遠程控制服務器，支持命令執行和文件傳輸。

✨ 主要特性

• 安全連接：支持密碼和私鑰兩種認證方式。
• 命令執行：可在遠程服務器上執行命令並獲取輸出。
• 文件傳輸：支持 SFTP 上傳、下載、讀寫文件。
• 目錄操作：能夠列出目錄、創建目錄、刪除文件/目錄以及重命名。
• 自動連接：支持通過環境變量預配置服務器，啟動時自動連接。
• 會話管理：支持多會話併發，可列出和斷開會話。
• 超時控制：連接和命令執行都支持超時設置。

📦 安裝指南

# 克隆項目
git clone https://github.com/lilyjem/ssh.git
cd ssh

# 安裝依賴
npm install

# 構建項目
npm run build

📚 詳細文檔

配置方式

在 Cursor 中配置

在 Cursor 設置中找到 MCP 配置（~/.cursor/mcp.json 或通過設置界面），添加以下配置：

• 方式一：預配置服務器（推薦） 通過環境變量預配置服務器信息，啟動時自動連接：

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

使用私鑰認證（更安全）：

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "root",
        "SSH_PRIVATE_KEY_PATH": "~/.ssh/id_rsa",
        "SSH_PASSPHRASE": "optional-passphrase"
      }
    }
  }
}

• 方式二：手動連接 不配置環境變量，使用時通過 ssh_connect 工具手動連接：

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"]
    }
  }
}

在 Claude Desktop 中配置

編輯 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

在 Claude Code (VS Code 擴展) 中配置

在項目根目錄創建 .mcp.json 文件：

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PRIVATE_KEY_PATH": "~/.ssh/id_rsa"
      }
    }
  }
}

或者在 VS Code 設置中配置全局 MCP 服務器。

在 Codex CLI 中配置

編輯 Codex 配置文件 ~/.codex/config.json：

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

使用 npx 運行（無需克隆）

如果項目已發佈到 npm，可以直接使用 npx：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["ssh"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

路徑說明

配置中的 /path/to/ssh/dist/index.js 需要替換為實際路徑：

• Windows：C:/Users/yourname/projects/ssh/dist/index.js
• macOS/Linux：/home/yourname/projects/ssh/dist/index.js

提示：Windows 路徑可以使用正斜槓 / 或雙反斜槓 \\

環境變量

*注：密碼、私鑰內容、私鑰路徑三者至少提供一個

工具列表

SSH 連接管理

• ssh_connect：創建新的 SSH 連接（預配置服務器時可選）。
  • 參數：
    • host (string, 必填)：服務器地址。
    • port (number, 可選)：SSH 端口，默認 22。
    • username (string, 必填)：用戶名。
    • password (string, 可選)：密碼。
    • privateKey (string, 可選)：私鑰內容。
    • passphrase (string, 可選)：私鑰密碼。
• ssh_exec：執行遠程命令。預配置服務器時無需提供 session_id。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • command (string, 必填)：要執行的命令。
    • timeout (number, 可選)：超時時間（毫秒）。

示例：ssh_exec(command="ls -la /var/log")

• ssh_list_sessions：列出所有活躍的 SSH 會話。
• ssh_disconnect：斷開 SSH 連接。
  • 參數：
    • session_id (string, 必填)：要斷開的會話 ID。

SFTP 文件操作

• sftp_list：列出遠程目錄內容。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • path (string, 可選)：目錄路徑，默認 /。

示例：sftp_list(path="/home/user")

• sftp_upload：上傳本地文件到遠程服務器。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • local_path (string, 必填)：本地文件路徑。
    • remote_path (string, 必填)：遠程目標路徑。

示例：sftp_upload(local_path="/local/file.txt", remote_path="/home/user/file.txt")

• sftp_download：從遠程服務器下載文件到本地。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • remote_path (string, 必填)：遠程文件路徑。
    • local_path (string, 必填)：本地目標路徑。

示例：sftp_download(remote_path="/var/log/syslog", local_path="/local/logs/syslog.txt")

• sftp_read：讀取遠程文件內容（適用於文本文件）。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • path (string, 必填)：遠程文件路徑。
    • encoding (string, 可選)：編碼，默認 utf-8。

示例：sftp_read(path="/etc/nginx/nginx.conf")

• sftp_write：寫入內容到遠程文件。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • path (string, 必填)：遠程文件路徑。
    • content (string, 必填)：要寫入的內容。

示例：sftp_write(path="/home/user/test.txt", content="Hello World")

• sftp_delete：刪除遠程文件或空目錄。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • path (string, 必填)：要刪除的路徑。

示例：sftp_delete(path="/home/user/old-file.txt")

• sftp_mkdir：創建遠程目錄。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • path (string, 必填)：目錄路徑。

示例：sftp_mkdir(path="/home/user/new-folder")

• sftp_rename：重命名或移動遠程文件/目錄。
  • 參數：
    • session_id (string, 可選)：會話 ID。
    • old_path (string, 必填)：原路徑。
    • new_path (string, 必填)：新路徑。

示例：sftp_rename(old_path="/home/user/old.txt", new_path="/home/user/new.txt")

限制說明

安全注意事項

⚠️ 重要提示

1. 憑據保護：密碼和私鑰僅在內存中保存，不會持久化到磁盤。
2. 日誌安全：日誌中不會打印密碼和私鑰內容。
3. 會話清理：服務關閉時會自動清理所有會話。
4. 命令限制：命令長度限制為 1000 字符，避免濫用。
5. 輸出限制：輸出超過 25000 字符會被截斷。
6. 環境變量：建議使用私鑰認證而非密碼，更安全。
7. 配置文件安全：不要將包含密碼的配置文件提交到版本控制。

技術棧

• 運行時：Node.js 18+
• 語言：TypeScript 5
• MCP SDK：@modelcontextprotocol/sdk
• SSH 庫：ssh2
• 參數校驗：Zod
• 測試框架：Vitest

💻 使用示例

預配置服務器模式

配置好環境變量後，服務啟動時會自動連接，可以直接使用：

用戶：查看服務器上的 /var/log 目錄
AI：調用 sftp_list(path="/var/log")

用戶：查看 nginx 配置
AI：調用 sftp_read(path="/etc/nginx/nginx.conf")

用戶：重啟 nginx 服務
AI：調用 ssh_exec(command="systemctl restart nginx")

用戶：上傳本地的配置文件到服務器
AI：調用 sftp_upload(local_path="/local/config/app.conf", remote_path="/etc/app/app.conf")

手動連接模式

用戶：連接到我的服務器 192.168.1.100
AI：調用 ssh_connect(host="192.168.1.100", username="root", password="xxx")
    返回 session_id

用戶：執行 ls 命令
AI：調用 ssh_exec(session_id="xxx", command="ls -la")

用戶：斷開連接
AI：調用 ssh_disconnect(session_id="xxx")

🔧 技術細節

開發

# 運行測試
npm test

# 監聽模式運行測試
npm run test:watch

# 開發模式（熱重載）
npm run dev

# 構建
npm run build

📄 許可證

MIT License - 詳見 LICENSE 文件