Linuxssh MCP

🚀 Linux SSH MCP Remote Command Execution Tool

A Linux SSH remote operation and maintenance toolset based on MCP (Model Context Protocol), supporting functions such as command execution, file transfer, directory management, and interactive sessions.

✨ Features

🚀 Quick Start

1. Installation

cd LinuxSSH_MCP
python -m venv .venv

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

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

2. Startup

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

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

📚 MCP Client Configuration

Claude Desktop / Claude Code Configuration

Add the following content to the MCP configuration file (replace PATH with the actual path):

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

Module Configuration

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

⚙️ Environment Variable Configuration

Support overriding default configurations via environment variables (prefix: SSH_MCP_):

📄 MCP Tool List (14 tools)

Credential Management

• auth_store_credentials - Store SSH credentials in keyring

Command Execution

• ssh_execute - Execute a single command
• ssh_execute_batch - Execute commands in batch
• ssh_execute_script - Execute a shell script
• ssh_system_info - Get system information
• ssh_search_content - Remote grep search
• ssh_health_check - SSH connection health check

Cache Management

• ssh_session_info - View cache status
• ssh_clear_cache - Clear the cache

File Transfer

• file_upload - Upload a file
• file_download - Download a file
• file_info - Get file information

Directory Operations

• dir_list - Directory listing (paginated)
• dir_interactive - Interactive session

📁 Project Structure

LinuxSSH_MCP/
├── linux_ssh_mcp/              # Core module
│   ├── __init__.py             # Package initialization
│   ├── __main__.py             # Module entry point
│   ├── mcp_server.py           # MCP protocol layer, 14 tool interfaces
│   ├── ssh_manager.py          # Core of SSH command execution
│   ├── connection_pool.py      # Connection pool (background cleanup + request merging + indexing)
│   ├── security.py             # Command security verification (blacklist/warnings/whitelist)
│   ├── exceptions.py           # 6-level structured exception hierarchy
│   ├── types.py                # TypedDict type definitions
│   ├── cache_manager.py        # TTL+LRU cache management
│   ├── directory_manager.py    # Directory management and interactive sessions
│   ├── file_transfer_manager.py # File upload and download
│   ├── auth_manager.py         # Credential management (keyring)
│   ├── config_manager.py       # Configuration file management
│   ├── settings.py             # Pydantic configuration
│   ├── constants.py            # Constant definitions
│   ├── token_optimizer.py      # Token optimizer
│   └── logger.py               # Log configuration (loguru)
├── tests/                      # Test cases (76 tests)
│   ├── test_connection_pool.py # Connection pool tests (34 tests)
│   ├── test_security.py        # Security verification tests (27 tests)
│   ├── test_exceptions.py      # Exception system tests (15 tests)
│   ├── test_ssh_manager.py     # SSH management tests
│   ├── test_auth_manager.py    # Credential management tests
│   ├── test_cache_manager.py   # Cache management tests
│   └── ...                     # Other module tests
├── main.py                     # Entry file
├── pyproject.toml              # Project configuration (build/mypy/ruff/pytest)
├── requirements.txt            # Dependency list
├── .env.example                # Environment variable example
└── .gitignore                  # Git ignore rules

🔧 Technical Stack

💻 Development

Run Tests

# Run all tests
.venv/Scripts/python -m pytest tests/ -v

# Run tests for a specific module
.venv/Scripts/python -m pytest tests/test_connection_pool.py -v

# Check test coverage
.venv/Scripts/python -m pytest tests/ --cov=linux_ssh_mcp --cov-report=term-missing

Code Quality Checks

# Type checking
.venv/Scripts/python -m mypy linux_ssh_mcp/

# Code style checking
.venv/Scripts/python -m ruff check linux_ssh_mcp/

# Automatic fix
.venv/Scripts/python -m ruff check --fix linux_ssh_mcp/

📄 License

MIT License