ssh-tool

Enhanced SSH MCP tool, forked from ssh-mcp-server with sudo elevation, command length limits, Windows status collection, and more.

中文文档

Tools

| Tool | Description | |---|---| | execute-command | Execute commands on remote servers | | sudo-exec | Execute commands with sudo elevation (requires sudoPassword configured) | | upload | Upload local files to remote servers | | download | Download files from remote servers to local | | list-servers | List all configured SSH servers and their status |

Command Line Options

--config-file       JSON config file path (recommended for multi-server setup)
--ssh-config-file   SSH config file path (default: ~/.ssh/config)
--ssh               SSH connection config (JSON string or legacy format, repeatable)
-h, --host          SSH server address or alias from ~/.ssh/config
-p, --port          SSH port
-u, --username      SSH username
-w, --password      SSH password
-k, --privateKey    SSH private key file path
-P, --passphrase    Private key passphrase
-W, --whitelist     Command whitelist (comma-separated regex patterns)
-B, --blacklist     Command blacklist (comma-separated regex patterns)
-s, --socksProxy    SOCKS proxy address, e.g. socks://user:pass@host:port
--sudoPassword      Password for sudo elevation
--maxChars          Max command length in characters (0 or unset = no limit)
--allowed-local-paths
                   Local paths allowed for upload/download in legacy single-server mode, comma-separated
--pty               Allocate pseudo-tty for command execution (default: true)
--pre-connect       Pre-connect to all configured servers on startup

MCP Configuration

Each argument and its value must be separate elements in the args array.

Single Server + sudo

{
  "mcpServers": {
    "ssh-tool": {
      "command": "node",
      "args": [
        "/path/to/ssh-tool/build/index.js",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "loginPwd",
        "--sudoPassword", "sudoPwd",
        "--maxChars", "10000",
        "--allowed-local-paths", "/Users/alice/project,/tmp"
      ]
    }
  }
}

With --sudoPassword configured, AI can call the sudo-exec tool. Without it, sudo-exec returns an error.

Using Private Key

{
  "mcpServers": {
    "ssh-tool": {
      "command": "node",
      "args": [
        "/path/to/ssh-tool/build/index.js",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

Using ~/.ssh/config Alias

{
  "mcpServers": {
    "ssh-tool": {
      "command": "node",
      "args": [
        "/path/to/ssh-tool/build/index.js",
        "--host", "myserver"
      ]
    }
  }
}

With the following ~/.ssh/config:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

Command-line arguments take precedence over SSH config values.

Command Whitelist / Blacklist

Whitelist — only allow ls, cat, df:

"--whitelist", "^ls( .*)?,^cat .*,^df.*"

Blacklist — block rm, shutdown, reboot:

"--blacklist", "^rm .*,^shutdown.*,^reboot.*"

When both are specified, a command must pass the whitelist first, then the blacklist.

Multi-Server Configuration

Config File (Recommended)

Create ssh-config.json:

[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "xxx",
    "sudoPassword": "sudoXxx",
    "maxChars": 8000,
    "allowedLocalPaths": ["/Users/alice/project", "/tmp"]
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "sudoPassword": "sudoYyy"
  }
]

Object format is also supported:

{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "xxx",
    "sudoPassword": "sudoXxx",
    "allowedLocalPaths": ["/Users/alice/project", "/tmp"]
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy"
  }
}

Reference in MCP config:

{
  "mcpServers": {
    "ssh-tool": {
      "command": "node",
      "args": [
        "/path/to/ssh-tool/build/index.js",
        "--config-file", "/path/to/ssh-config.json"
      ]
    }
  }
}

--ssh Parameter

"--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"xxx\",\"sudoPassword\":\"sudoXxx\",\"allowedLocalPaths\":[\"/Users/alice/project\",\"/tmp\"]}",
"--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"allowedLocalPaths\":[\"/Users/alice/project\",\"/tmp\"]}"

Use connectionName in tool calls to target a specific connection:

{
  "tool": "sudo-exec",
  "params": {
    "cmdString": "systemctl restart nginx",
    "connectionName": "prod"
  }
}

Local File Access for Upload / Download

The file transfer tools validate local paths before reading or writing files. With the legacy single-server options (--host, --port, --username, etc.), use --allowed-local-paths and separate multiple roots with commas:

"--allowed-local-paths", "/Users/alice/project,/tmp"

For --config-file and repeated --ssh JSON configurations, put allowedLocalPaths inside each server config. This is the value actually attached to a named connection such as dev or prod:

{
  "name": "dev",
  "host": "1.2.3.4",
  "port": 22,
  "username": "alice",
  "privateKey": "~/.ssh/id_rsa",
  "allowedLocalPaths": ["/Users/alice/project", "/tmp"]
}

When a string is used in JSON instead of an array, split paths with |, for example "/Users/alice/project|/tmp". The command-line form and the JSON form deliberately use different separators because they are parsed by different configuration branches.

Command Execution Timeout

Both execute-command and sudo-exec support a timeout parameter (milliseconds, default 30000). On timeout the connection stays alive — only the current command is terminated. Error responses include structured code / message / retriable fields.

Changes from Upstream

Forked from classfang/ssh-mcp-server v1.6.1. Key changes:

• Added sudo-exec tool using printf | sudo -S pipe, with password configured in the config file
• Added --maxChars to limit command length
• Status collection now supports Windows (via PowerShell commands); Linux logic unchanged
• SSHConnectionManager gained resetInstance() for testing
• socks dependency changed to dynamic import, loaded only when proxy is configured
• File transfer tools (upload / download) are enabled by default; legacy single-server setups use --allowed-local-paths, while named multi-server configs should set allowedLocalPaths on each server

Security

• Strongly recommended to use --whitelist to restrict executable commands
• sudoPassword is stored in local config files — ensure file permissions are set to 600
• Private keys are read into memory — ensure the runtime environment is trusted
• No built-in rate limiting — run behind a firewall in production