SSH MCP2 Server

SSH MCP2 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, transfer files, and manage remote servers securely via SSH.

Contents

• Quick Start
• Features
• Tools
• Client Setup
• Dangerous Command Protection
• Testing
• Disclaimer

Quick Start

# Run directly via npx
npx -y ssh-mcp2 -- --host=1.2.3.4 --port=22 --user=root --password=pass

Or add to your MCP client configuration (see Client Setup below).

Features

• 4 MCP tools: exec, sudo-exec, upload_file, download_file
• SSH password and key authentication
• Persistent SSH connection with automatic reconnection
• su elevation for interactive root shell sessions
• Dangerous command protection with customizable deny rules
• Configurable command timeout (default: 60s)
• Configurable max command length (default: 1000 chars)
• SFTP file upload and download

Tools

exec

Execute a shell command on the remote SSH server and return the output.

Parameters:

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

sudo-exec

Execute a shell command with sudo elevation.

Parameters:

• command (required): Shell command to execute as root using sudo
• description (optional): Description of what this command will do

Notes:

• When the command starts with sudo and --sudoPassword is configured, exec automatically pipes the password via sudo -S (same as sudo-exec).
• Requires --sudoPassword to be set for password-protected sudo
• Can be disabled via --disableSudo flag
• For persistent root access, use --suPassword instead (establishes a root shell through exec and sudo-exec)

upload_file

Upload a file from the local machine to the remote server via SFTP.

Parameters:

• localPath (required): Absolute path to the local file
• remotePath (required): Absolute destination path on the remote server
• permissions (optional): File permissions in octal, e.g. '0755'

download_file

Download a file from the remote server to the local machine via SFTP.

Parameters:

• remotePath (required): Absolute path to the file on the remote server
• localPath (required): Absolute destination path on the local machine

Client Setup

Required CLI Arguments:

• --host: Hostname or IP of the remote server
• --user: SSH username

Optional CLI Arguments:

• --port: SSH port (default: 22)
• --password: SSH password (or use --key for key-based auth)
• --key: Path to private SSH key file
• --sudoPassword: Password for sudo elevation
• --suPassword: Password for su elevation (persistent root shell)
• --timeout: Command execution timeout in milliseconds (default: 60000)
• --maxChars: Maximum characters for the command input (default: 1000). Set to none or 0 to disable the limit.
• --disableSudo: Disable the sudo-exec tool
• --deny-rules: Path to a JSON file with dangerous command patterns to block

Opencode / Claude Desktop / Cursor

{
  "mcpServers": {
    "ssh-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp2",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none",
        "--deny-rules=/home/user/.config/ssh-deny-rules.json"
      ]
    }
  }
}

Claude Code

# Basic password auth
claude mcp add --transport stdio ssh-server -- npx -y ssh-mcp2 -- --host=192.168.1.100 --user=admin --password=your_password

# With sudo support and deny rules
claude mcp add --transport stdio ssh-server -- npx -y ssh-mcp2 -- --host=192.168.1.100 --user=admin --password=your_password --sudoPassword=sudo_pass --deny-rules=/home/user/deny.json

Dangerous Command Protection

The --deny-rules flag lets you define a blocklist of dangerous shell commands. When a command matches any rule in the file, it is rejected before execution.

Rule File Format

[
  { "pattern": "^rm\\s+-[a-z]*r[a-z]*f[a-z]*\\s+/\\s*(?:--no-preserve-root)?\\s*$", "reason": "Recursive force removal targeting root (/)" },
  { "pattern": "^reboot\\b", "reason": "Server restart denied" },
  { "pattern": "^:\(\\)\\s*\\{", "reason": "Fork bomb detected" }
]

Each entry has:

• pattern: JavaScript regular expression (case-insensitive). ^ anchors to the command start, \\b is a word boundary.
• reason: Human-readable message returned to the AI when the command is blocked.

Template

A reference template with 14 common dangerous patterns is included in the package:

build/deny-rules.default.json

Copy and customize it to your needs:

cp node_modules/ssh-mcp2/build/deny-rules.default.json ~/.config/ssh-deny-rules.json

Behavior

| --deny-rules not set | No command filtering — AI can execute any command | | --deny-rules=<path> | Only commands matching rules in that file are blocked |

Testing

MCP Inspector

npm run inspect

Unit Tests

npm test

(requires Docker or a running SSH server on localhost:2222 for integration tests)

Disclaimer

SSH MCP2 Server is provided under the MIT License. Use at your own risk. This project is not affiliated with or endorsed by any SSH or MCP provider.