Linuxssh MCP

🚀 Linux SSH MCP 遠程命令執行工具

這是一款基於 MCP (Model Context Protocol) 的 Linux SSH 遠程運維工具集，具備命令執行、文件傳輸、目錄管理、交互式會話等實用功能，能有效提升遠程運維的效率與安全性。

✨ 主要特性

🚀 快速開始

📦 安裝指南

cd LinuxSSH_MCP
python -m venv .venv

# Windows
.\.venv\Scripts\python -m pip install -e ".[dev]"

# Linux/macOS
.venv/bin/pip install -e ".[dev]"

啟動步驟

# Windows
.\.venv\Scripts\python main.py

# Linux/macOS
.venv/bin/python main.py

📚 詳細文檔

MCP 客戶端配置

Claude Desktop / Claude Code 配置

在 MCP 配置文件中添加以下內容（將 PATH 替換為實際路徑）：

{
  "mcpServers": {
    "linux-ssh-mcp": {
      "command": "PATH/LinuxSSH_MCP/.venv/Scripts/python.exe",
      "args": [
        "PATH/LinuxSSH_MCP/main.py"
      ]
    }
  }
}

模塊方式配置

{
  "mcpServers": {
    "linux-ssh-mcp": {
      "command": "PATH/LinuxSSH_MCP/.venv/Scripts/python.exe",
      "args": ["-m", "linux_ssh_mcp"]
    }
  }
}

環境變量配置

支持通過環境變量覆蓋默認配置（前綴：SSH_MCP_）：

MCP 工具清單 (14 個)

憑據管理

• auth_store_credentials - 存儲 SSH 憑據到 keyring

命令執行

• ssh_execute - 執行單條命令
• ssh_execute_batch - 批量執行命令
• ssh_execute_script - 執行 Shell 腳本
• ssh_system_info - 獲取系統信息
• ssh_search_content - 遠端 grep 搜索
• ssh_health_check - SSH 連接健康檢查

緩存管理

• ssh_session_info - 查看緩存狀態
• ssh_clear_cache - 清理緩存

文件傳輸

• file_upload - 上傳文件
• file_download - 下載文件
• file_info - 獲取文件信息

目錄操作

• dir_list - 目錄列表(分頁)
• dir_interactive - 交互式會話

項目結構

LinuxSSH_MCP/
├── linux_ssh_mcp/              # 核心模塊
│   ├── __init__.py             # 包初始化
│   ├── __main__.py             # 模塊入口
│   ├── mcp_server.py           # MCP協議層，14個工具接口
│   ├── ssh_manager.py          # SSH命令執行核心
│   ├── connection_pool.py      # 連接池（後臺清理+請求合併+索引）
│   ├── security.py             # 命令安全校驗（黑名單/警告/白名單）
│   ├── exceptions.py           # 6級結構化異常層次
│   ├── types.py                # TypedDict 類型定義
│   ├── cache_manager.py        # TTL+LRU緩存管理
│   ├── directory_manager.py    # 目錄管理與交互式會話
│   ├── file_transfer_manager.py # 文件上傳下載
│   ├── auth_manager.py         # 憑據管理(keyring)
│   ├── config_manager.py       # 配置文件管理
│   ├── settings.py             # Pydantic配置
│   ├── constants.py            # 常量定義
│   ├── token_optimizer.py      # Token優化器
│   └── logger.py               # 日誌配置(loguru)
├── tests/                      # 測試用例 (76個測試)
│   ├── test_connection_pool.py # 連接池測試 (34個)
│   ├── test_security.py        # 安全校驗測試 (27個)
│   ├── test_exceptions.py      # 異常體系測試 (15個)
│   ├── test_ssh_manager.py     # SSH管理測試
│   ├── test_auth_manager.py    # 憑據管理測試
│   ├── test_cache_manager.py   # 緩存管理測試
│   └── ...                     # 其他模塊測試
├── main.py                     # 入口文件
├── pyproject.toml              # 項目配置(構建/mypy/ruff/pytest)
├── requirements.txt            # 依賴列表
├── .env.example                # 環境變量示例
└── .gitignore                  # Git忽略規則

技術棧

開發

運行測試

# 運行全部測試
.venv/Scripts/python -m pytest tests/ -v

# 運行特定模塊測試
.venv/Scripts/python -m pytest tests/test_connection_pool.py -v

# 查看覆蓋率
.venv/Scripts/python -m pytest tests/ --cov=linux_ssh_mcp --cov-report=term-missing

代碼質量檢查

# 類型檢查
.venv/Scripts/python -m mypy linux_ssh_mcp/

# 代碼風格檢查
.venv/Scripts/python -m ruff check linux_ssh_mcp/

# 自動修復
.venv/Scripts/python -m ruff check --fix linux_ssh_mcp/

📄 許可證

MIT License