SSH MCP Server

SSH MCP Server

SSH MCP Server is a local Model Context Protocol (MCP) server that exposes SSH control for Linux and Windows systems, enabling LLMs and other MCP clients to execute shell commands securely via SSH.

Contents

• Quick Start
• Features
• Installation
• Client Setup
• Testing
• Disclaimer
• Support

Quick Start

• Install SSH MCP Server
• Configure SSH MCP Server
• Set up your MCP Client (e.g. Claude Desktop, Cursor, etc)
• Execute remote shell commands on your Linux or Windows server via natural language

Features

• MCP-compliant server exposing SSH capabilities
• Execute shell commands on remote Linux and Windows systems
• Secure authentication via password or SSH key
• Built with TypeScript and the official MCP SDK
• Configurable timeout protection with automatic process abortion
• Graceful timeout handling - attempts to kill hanging processes before closing connections

Tools

• exec: Execute a shell command on the remote server

  • Parameters:
    • command (required): Shell command to execute on the remote SSH server
    • description (optional): Optional description of what this command will do (appended as a comment)
  • Timeout Configuration:

• sudo-exec: Execute a shell command with sudo elevation

  • Parameters:
    • command (required): Shell command to execute as root using sudo
    • description (optional): Optional description of what this command will do (appended as a comment)
  • Notes:
    • Requires --sudoPassword to be set for password-protected sudo
    • Can be disabled by passing the --disableSudo flag at startup if sudo access is not needed or not available
    • For persistent root access, consider using --suPassword instead which establishes a root shell
    • Tool will not be available at all if server is started with --disableSudo
  • Timeout Configuration:
    • Timeout is configured via command line argument --timeout (in milliseconds)
    • Default timeout: 60000ms (1 minute)
    • When a command times out, the server automatically attempts to abort the running process before closing the connection
  • Max Command Length Configuration:
    • Max command characters are configured via --maxChars
    • Default: 1000
    • No-limit mode: set --maxChars=none or any <= 0 value (e.g. --maxChars=0)

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

Client Setup

You can configure your IDE or LLM like Cursor, Windsurf, Claude Desktop to use this MCP Server.

Required Parameters:

• host: Hostname or IP of the Linux or Windows server
• user: SSH username

Optional Parameters:

• port: SSH port (default: 22)
• password: SSH password (or use key for key-based auth)
• key: Path to private SSH key
• sudoPassword: Password for sudo elevation (when executing commands with sudo)
• suPassword: Password for su elevation (when you need a persistent root shell)
• timeout: Command execution timeout in milliseconds (default: 60000ms = 1 minute)
• maxChars: Maximum allowed characters for the command input (default: 1000). Use none or 0 to disable the limit.
• disableSudo: Flag to disable the sudo-exec tool completely. Useful when sudo access is not needed or not available.

{
    "mcpServers": {
        "ssh-mcp": {
            "command": "npx",
            "args": [
                "ssh-mcp",
                "-y",
                "--",
                "--host=1.2.3.4",
                "--port=22",
                "--user=root",
                "--password=pass",
                "--key=path/to/key",
                "--timeout=30000",
                "--maxChars