### Common Command Template Examples

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Provides examples of other common command templates for different execution environments.

```text
sudo bash -c '<command>'
docker exec -i mycontainer sh -c '<command>'
ssh jumphost '<command>'
```

--------------------------------

### Example Response for List SSH Servers

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

This is an example of the JSON response when listing all available SSH server configurations.

```json
[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]
```

--------------------------------

### Full SSHConfig Example

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Example of a production server configuration using `SSHConfig` with security options like command whitelisting and blacklisting.

```typescript
// Full example — production server with all security options
const prodConfig: SSHConfig = {
  name: "prod",
  host: "10.0.0.2",
  port: 22,
  username: "deploy",
  privateKey: "/home/deploy/.ssh/id_ed25519",
  passphrase: process.env.SSH_MCP_PASSPHRASE,
  commandWhitelist: ["^ls( .*)?$", "^cat ", "^tail -f ", "^journalctl "],
  commandBlacklist: ["^rm -rf", "^dd ", "^mkfs"],
  allowedLocalPaths: ["/home/deploy/releases"],
  allowedRemotePaths: ["/var/www/html", "/tmp/deploy"],
  transportMode: "exec",
  pty: true,
};
```

--------------------------------

### Configure SSH MCP Server to Connect on Startup

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Use the `--pre-connect` flag to establish all SSH connections immediately when the server starts, instead of lazily.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json",
        "--pre-connect"
      ]
    }
  }
}
```

--------------------------------

### Example of Command Templating in Action

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Illustrates the actual command sent when a directory is specified and a command is executed using a template.

```text
su root -c 'cd -- "/data" && ls /app'
```

--------------------------------

### ToolError Response Example

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Example of a structured error response object returned by MCP tools on failure. The `retriable` flag indicates whether a retry is safe.

```json
{
  "code": "COMMAND_TIMEOUT",
  "message": "[timeout] Command timed out after 30000ms",
  "retriable": true   // true = safe to retry; false = fix input or config first
}
```

--------------------------------

### Configure Command Template for User Switching

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Use `command-template` to wrap commands for scenarios like switching users with `su`. The template is applied after directory changes.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "10.0.0.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "xxx",
        "--command-template", "su root -c '<command>'"]}}
}
```

--------------------------------

### Wrap Commands with a Template (su)

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

The `--command-template` option allows wrapping every executed command within a specified template. This is useful for tasks like switching users with `su` or running commands in specific environments. The `<command>` placeholder is replaced by the actual command.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "10.0.0.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "xxx",
        "--command-template", "su root -c '<command>'
      ]
    }
  }
}
```

--------------------------------

### Configure SSH MCP Server with Command Template

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Wrap commands in a template for execution with `su`, `sudo`, or within containers. The `<command>` placeholder is replaced by the full command.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "10.0.0.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "pass",
        "--command-template", "sudo bash -c '<command>'"]
    }
  }
}
```

```shell
// Executing: ls /app  with directory /data sends:
sudo bash -c 'cd -- "/data" && ls /app'

// Other useful templates:
// "su root -c '<command>'"
// "docker exec -i mycontainer sh -c '<command>'"
// "ssh jumphost '<command>'"
```

--------------------------------

### Configure Command Access Control with Whitelist and Blacklist

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Implement command access control using comma-separated regex patterns for `--whitelist` and `--blacklist`. The whitelist is checked first, followed by the blacklist. Both must pass for a command to be executed.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "10.0.0.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "pass",
        "--whitelist", "^ls( .*)?$,^cat .*,^df.*,^free.*,^ps . *",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*,^mkfs.*"
      ]
    }
  }
}
```

--------------------------------

### Environment Variables for SSH MCP Server

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Demonstrates launching the ssh-mcp-server with sensitive information like private key passphrase and 2FA codes provided via environment variables.

```bash
# Launch with passphrase and 2FA code via environment
SSH_MCP_PASSPHRASE=mykeypass SSH_MCP_2FA_CODE=654321 \
  npx @fangjunjie/ssh-mcp-server \
    --host secure.example.com \
    --port 22 \
    --username admin \
    --privateKey ~/.ssh/id_rsa \
    --try-keyboard
```

--------------------------------

### Configure Multi-Factor Authentication (MFA) with Keyboard Interaction

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Enable `tryKeyboard` when the SSH server requires multi-factor authentication. This allows for manual input of the 2FA code when prompted after password and private key authentication.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "example.com",
        "--port", "22",
        "--username", "user",
        "--password", "your_password",
        "--privateKey", "/path/to/key",
        "--try-keyboard"]
    }
  }
}
```

--------------------------------

### Configure Multiple SSH Connections via Configuration File (Object Format)

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Manage multiple SSH connections using an object format in a JSON configuration file. Each key represents a connection name, with its value containing the connection details.

```json
{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  "bastion": {
    "host": "9.9.9.9",
    "port": 22,
    "username": "ops",
    "password": "pwd123456",
    "transportMode": "shell",
    "shellReadyTimeoutMs": 15000,
    "shellCommandTimeoutMs": 45000
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
}
```

--------------------------------

### Configure Single Connection via Private Key

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Configure the server to use a private key for authentication. Optionally, provide a passphrase if the private key is protected. The path to the private key can be relative or absolute.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.10",
        "--port", "22",
        "--username", "deploy",
        "--privateKey", "~/.ssh/id_ed25519",
        "--passphrase", "keypassword"
      ]
    }
  }
}
```

--------------------------------

### Configure Multiple SSH Connections via Configuration File (Array Format)

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Manage multiple SSH connections by defining them in an array format within a JSON configuration file. Each object specifies connection details like name, host, port, username, password, and proxy settings.

```json
[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "bastion",
    "host": "9.9.9.9",
    "port": 22,
    "username": "ops",
    "password": "pwd123456",
    "transportMode": "shell",
    "shellReadyTimeoutMs": 15000,
    "shellCommandTimeoutMs": 45000
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "secure-server",
    "host": "secure.example.com",
    "port": 22,
    "username": "admin",
    "password": "your_password",
    "privateKey": "/path/to/private/key",
    "tryKeyboard": true
  }
]
```

--------------------------------

### Load Multiple Connections from JSON Config File

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Use the `--config-file` option to load multiple server connections from a JSON file. The file can contain an array of connection objects or a named object map. This option takes precedence over other connection flags.

```json
// ssh-config.json — array format
[
  {
    "name": "dev",
    "host": "10.0.0.1",
    "port": 22,
    "username": "alice",
    "password": "devpass",
    "commandWhitelist": ["^ls", "^cat ", "^df"]
  },
  {
    "name": "prod",
    "host": "10.0.0.2",
    "port": 22,
    "username": "bob",
    "privateKey": "/home/bob/.ssh/id_rsa",
    "allowedRemotePaths": ["/var/www", "/tmp/uploads"],
    "commandWhitelist": ["^ls", "^tail "]
  },
  {
    "name": "bastion",
    "host": "bastion.example.com",
    "port": 22,
    "username": "ops",
    "password": "bastionpwd",
    "transportMode": "shell",
    "shellReadyTimeoutMs": 15000,
    "shellCommandTimeoutMs": 45000
  }
]
```

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "/home/user/ssh-config.json"
      ]
    }
  }
}
```

--------------------------------

### List All SSH Servers using MCP Tool

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Use the `list-servers` tool to retrieve all configured SSH server details. This is useful for managing multiple server connections.

```json
{
  "tool": "list-servers",
  "params": {}
}
```

--------------------------------

### Configure SSH Server with Private Key

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

This snippet shows how to configure an SSH connection using a private key for authentication. The path to your private key file should be specified correctly.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}
```

--------------------------------

### Use SSH Config File with SSH MCP Server

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Launch the SSH MCP server using a configuration file by specifying the `--config-file` parameter. This is the recommended method for managing multiple connections.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}
```

--------------------------------

### Configure SSH Server with Private Key and Passphrase

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

For SSH connections secured with a private key that has a passphrase, include the passphrase in the configuration. Ensure the passphrase is correct to establish the connection.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}
```

--------------------------------

### SSH MCP Server Command Line Options

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Reference for command-line options available for configuring and running the SSH MCP server, including connection details, security settings, and transport modes.

```text
Options:
  --config-file       JSON configuration file path (recommended for multiple servers)
  --ssh-config-file   SSH config file path (default: ~/.ssh/config)
  --ssh               SSH connection configuration (can be JSON string or legacy format)
  -h, --host          SSH server host address or alias from SSH config
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -a, --agent         SSH agent socket path
  --try-keyboard      Enable keyboard-interactive authentication for 2FA/MFA (default: false)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  --allowed-local-paths   Additional allowed local paths for upload/download, comma-separated
  --allowed-remote-paths  Allowed remote (POSIX, absolute) paths for SFTP upload/download, comma-separated
  --transport-mode    SSH transport mode: exec or shell (default: exec)
  --shell-ready-timeout   Shell readiness probe timeout in milliseconds (default: 10000)
  --command-template  Command template, use <command> as placeholder (e.g., "su root -c '<command>'")
  --pty               Allocate pseudo-tty for command execution (default: true)
  --pre-connect       Pre-connect to all configured SSH servers on startup
```

--------------------------------

### list-servers

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

List all configured SSH connections, providing both a human-readable summary and a raw JSON array of connection details, including connection status and cached system information.

```APIDOC
## list-servers

### Description
Returns a human-readable summary and a raw JSON array of all configured SSH servers, including connection status and cached system info (hostname, OS, last updated) collected after each connection.

### Method
POST (implied by tool usage)

### Endpoint
(Not explicitly defined, used as a tool command)

### Parameters
#### Request Body
- **tool** (string) - Required - Must be "list-servers"
- **params** (object) - Required - No parameters are required for this tool.

### Request Example
```json
{
  "tool": "list-servers",
  "params": {}
}
```

### Response
#### Success Response
- **string**: A human-readable summary of configured SSH servers.
- **array**: A raw JSON array containing detailed information for each configured SSH server, including connection status and system information.

### Example Response (Raw JSON)
```json
[
  {
    "name": "dev",
    "host": "10.0.0.1",
    "port": 22,
    "username": "alice",
    "connected": true,
    "status": {
      "reachable": true,
      "hostname": "dev-server",
      "osName": "Ubuntu 22.04.3 LTS",
      "kernelVersion": "5.15.0-78-generic",
      "uptime": "10 days, 4:32",
      "memory": { "free": "2.1 GB", "total": "8.0 GB" },
      "cpu": { "name": "Intel Core i7-9700", "usage": "12%" },
      "lastUpdated": "2024-07-01T12:00:00.000Z"
    }
  },
  {
    "name": "prod",
    "host": "10.0.0.2",
    "port": 22,
    "username": "bob",
    "connected": false
  }
]
```
```

--------------------------------

### Configure Single Connection via Username and Password

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Use this configuration in your MCP client's mcp.json to launch the server with username and password authentication. Ensure each argument and its value are separate array elements.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.10",
        "--port", "22",
        "--username", "deploy",
        "--password", "s3cr3t"
      ]
    }
  }
}
```

--------------------------------

### Connect Using Bastion/Jump Host with Shell Transport

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Configure the server to use `shell` transport mode for connecting through bastion or jump hosts. This mode is suitable when direct `exec` commands fail or when the remote side requires shell initialization. Note that `upload` and `download` are not supported in `shell` mode.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "bastion.example.com",
        "--port", "22",
        "--username", "ops",
        "--password", "pwd123456",
        "--transport-mode", "shell",
        "--shell-ready-timeout", "15000"
      ]
    }
  }
}
```

--------------------------------

### Read Connection Parameters from ~/.ssh/config

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Configure the server to read connection details like HostName, Port, User, and IdentityFile from an existing ~/.ssh/config file. CLI flags will override values from the config file.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/home/user/.ssh/config"
      ]
    }
  }
}
```

```ssh-config
# ~/.ssh/config
Host myserver
    HostName 10.0.0.5
    Port 2222
    User alice
    IdentityFile ~/.ssh/id_rsa
```

--------------------------------

### Restrict Commands with Whitelist

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Use the `--whitelist` option to specify a comma-separated list of regular expressions for commands that are permitted to run. This enhances security by limiting the server's capabilities.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}
```

--------------------------------

### Pass SSH Configuration Directly via JSON --ssh Argument

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Provide SSH connection configurations directly as JSON strings using the `--ssh` argument. This allows for inline configuration of multiple connections.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"]
    }
  }
}
```

--------------------------------

### Configure SSH Server with Username and Password

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Use this configuration for the simplest SSH connection using username and password authentication. Ensure 'command' and 'args' are correctly formatted for your MCP client.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}
```

--------------------------------

### Enable MFA with SSH MCP Server

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

To enable multi-factor authentication (password + private key + 2FA code), set the `--try-keyboard` flag. The 2FA code requires manual input at the prompt.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "example.com",
        "--port", "22",
        "--username", "user",
        "--password", "your_password",
        "--privateKey", "/path/to/key",
        "--try-keyboard"
      ]
    }
  }
}
```

--------------------------------

### Legacy SSH Connection Configuration

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Use the legacy comma-separated format for simple SSH connection configurations. Be aware of potential issues with special characters in passwords.

```bash
npx @fangjunjie/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"
```

--------------------------------

### Inline Multi-Connection Configuration via JSON

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Use the `--ssh` flag to pass JSON-encoded connection objects directly on the command line. This is preferred over the legacy comma-separated format, especially when passwords contain special characters.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"10.0.0.1\",\"port\":22,\"username\":\"alice\",\"password\":\"devpass\"}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"10.0.0.2\",\"port\":22,\"username\":\"bob\",\"privateKey\":\"/home/bob/.ssh/id_rsa\"}"
      ]
    }
  }
}
```

--------------------------------

### Connect Through a SOCKS Proxy

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Configure the server to connect to a target host that is only accessible through a SOCKS proxy. Requires specifying the proxy URL with authentication details.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}
```

--------------------------------

### Configure SSH MCP Server for Multi-Factor Authentication

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Enable keyboard-interactive authentication for MFA. OTP/2FA codes should be provided via the SSH_MCP_2FA_CODE environment variable.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "secure.example.com",
        "--port", "22",
        "--username", "admin",
        "--password", "adminpass",
        "--privateKey", "/home/admin/.ssh/id_rsa",
        "--try-keyboard"
      ],
      "env": {
        "SSH_MCP_2FA_CODE": "123456"
      }
    }
  }
}
```

--------------------------------

### download

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Download a file from the remote server to the local filesystem via SFTP. This operation is subject to the same local and remote path restrictions as `upload` and is not available in `shell` transport mode.

```APIDOC
## download

### Description
Transfers a file from the remote server to the local filesystem via SFTP. Subject to the same local and remote path restrictions as `upload`. Not available in `shell` transport mode.

### Method
POST (implied by tool usage)

### Endpoint
(Not explicitly defined, used as a tool command)

### Parameters
#### Request Body
- **tool** (string) - Required - Must be "download"
- **params** (object) - Required
  - **remotePath** (string) - Required - The absolute POSIX path on the remote server of the file to download.
  - **localPath** (string) - Required - The path on the local filesystem where the file will be saved.
  - **connectionName** (string) - Required - The name of the SSH connection to use.

### Request Example
```json
{
  "tool": "download",
  "params": {
    "remotePath": "/var/log/nginx/access.log",
    "localPath": "./logs/access.log",
    "connectionName": "prod"
  }
}
```

### Response
#### Success Response
- **string**: "File downloaded successfully"

#### Error Responses
- **LOCAL_FILE_WRITE_FAILED**: Failed to save file (e.g., permission denied).
- **SFTP_ERROR**: SFTP read failure on the remote server (e.g., file not found).
```

--------------------------------

### Use Configuration File with SSH MCP Server

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Specify a JSON configuration file using the `--config-file` argument to manage multiple SSH connections for the MCP server.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"]
    }
  }
}
```

--------------------------------

### List all configured SSH connections

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Retrieves a summary and raw JSON array of all configured SSH servers, including their connection status and cached system information.

```json
// Request (no parameters required)
{
  "tool": "list-servers",
  "params": {}
}
```

```text
// Example response text:
// Configured SSH servers:
// [connected] dev | alice@10.0.0.1:22 | hostname=dev-server | os=Ubuntu 22.04.3 LTS | updated=2024-07-01T12:00:00.000Z
// [disconnected] prod | bob@10.0.0.2:22
//
// Raw JSON:

```

```json
[
  {
    "name": "dev",
    "host": "10.0.0.1",
    "port": 22,
    "username": "alice",
    "connected": true,
    "status": {
      "reachable": true,
      "hostname": "dev-server",
      "osName": "Ubuntu 22.04.3 LTS",
      "kernelVersion": "5.15.0-78-generic",
      "uptime": "10 days, 4:32",
      "memory": { "free": "2.1 GB", "total": "8.0 GB" },
      "cpu": { "name": "Intel Core i7-9700", "usage": "12%" },
      "lastUpdated": "2024-07-01T12:00:00.000Z"
    }
  },
  {
    "name": "prod",
    "host": "10.0.0.2",
    "port": 22,
    "username": "bob",
    "connected": false
  }
]
```

--------------------------------

### Execute Command with Timeout Options

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Execute a command on a specific SSH connection with a defined timeout using the `timeout` parameter.

```json
{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}
```

--------------------------------

### Configure SSH MCP Server with SFTP Path Restrictions

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Restrict local and remote paths for SFTP operations using `--allowed-local-paths` and `--allowed-remote-paths`. Remote paths must be absolute POSIX paths.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "10.0.0.1",
        "--port", "22",
        "--username", "deploy",
        "--password", "pass",
        "--allowed-local-paths", "/home/deploy/uploads,/tmp/staging",
        "--allowed-remote-paths", "/var/www/html,/tmp/server-uploads"
      ]
    }
  }
}
```

--------------------------------

### Restrict Commands with Blacklist

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Use the `--blacklist` option to specify a comma-separated list of regular expressions for commands that are explicitly forbidden. This is crucial for preventing destructive operations.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}
```

--------------------------------

### Configure Shell Transport Mode for Bastion Host

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README_CN.md

Switch to `shell` transport mode when `exec` fails or when connecting to devices that require a fully initialized interactive shell, such as bastion hosts. Note that `upload`/`download` are not supported in this mode.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "bastion.example.com",
        "--port", "22",
        "--username", "ops",
        "--password", "pwd123456",
        "--transport-mode", "shell",
        "--shell-ready-timeout", "15000"]
    }
  }
}
```

--------------------------------

### upload

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Upload a local file to the remote server via SFTP. This operation is not available in `shell` transport mode. Local paths must be within the working directory or `allowedLocalPaths`, and remote paths must be absolute POSIX paths within `allowedRemotePaths`.

```APIDOC
## upload

### Description
Transfers a local file to the remote server via SFTP. Not available in `shell` transport mode. Local path must be within the working directory or `allowedLocalPaths`; remote path must be an absolute POSIX path within `allowedRemotePaths` (if configured).

### Method
POST (implied by tool usage)

### Endpoint
(Not explicitly defined, used as a tool command)

### Parameters
#### Request Body
- **tool** (string) - Required - Must be "upload"
- **params** (object) - Required
  - **localPath** (string) - Required - The path to the local file to upload.
  - **remotePath** (string) - Required - The absolute POSIX path on the remote server where the file will be uploaded.
  - **connectionName** (string) - Required - The name of the SSH connection to use.

### Request Example
```json
{
  "tool": "upload",
  "params": {
    "localPath": "./dist/app.tar.gz",
    "remotePath": "/var/www/releases/app.tar.gz",
    "connectionName": "prod"
  }
}
```

### Response
#### Success Response
- **string**: "File uploaded successfully"

#### Error Responses
- **LOCAL_PATH_NOT_ALLOWED**: Path traversal detected. Local path must be within the working directory or configured allowed local paths.
- **REMOTE_PATH_NOT_ALLOWED**: Remote path is not within the configured allowedRemotePaths.
- **UNSUPPORTED_IN_SHELL_MODE**: Current bastion shell mode does not support SFTP upload/download.
```

--------------------------------

### Configure Multiple SSH Connections via JSON Parameter

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Pass JSON-formatted configuration strings directly using the `--ssh` parameter. This method is useful for dynamic configuration.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
      ]
    }
  }
}
```

--------------------------------

### Environment Variables

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Lists environment variables that can be used to provide sensitive information or configure tool behavior.

```APIDOC
## Environment Variables

| Variable | Purpose |
|---|---|
| `SSH_MCP_PASSPHRASE` | Private key passphrase (alternative to `--passphrase` CLI flag) |
| `SSH_MCP_2FA_CODE` | One-time 2FA/OTP code for keyboard-interactive authentication |

```bash
# Launch with passphrase and 2FA code via environment
SSH_MCP_PASSPHRASE=mykeypass SSH_MCP_2FA_CODE=654321 \
  npx @fangjunjie/ssh-mcp-server \
    --host secure.example.com \
    --port 22 \
    --username admin \
    --privateKey ~/.ssh/id_rsa \
    --try-keyboard
```
```

--------------------------------

### Configure SSH MCP Server for Shell Transport Mode

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Use shell mode for interactive shells on bastion hosts. Upload and download operations are unavailable in this mode.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "bastion.example.com",
        "--port", "22",
        "--username", "ops",
        "--password", "bastionpwd",
        "--transport-mode", "shell",
        "--shell-ready-timeout", "15000"
      ]
    }
  }
}
```

--------------------------------

### Execute Command on Specific SSH Connection

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Execute a command on a specific SSH connection by providing the `connectionName` parameter. If omitted, the default connection is used.

```json
{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod"
  }
}
```

--------------------------------

### SSHConfig Interface

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Defines the structure for SSH connection options, used in configuration files, JSON strings, and internal maps.

```APIDOC
## `SSHConfig` Type Reference

The `SSHConfig` interface defines all connection options used in `--config-file` JSON, `--ssh` JSON strings, and the internal configuration map.

```typescript
interface SSHConfig {
  name?: string;                   // Connection name (required for multi-connection)
  host: string;                    // SSH server hostname or IP
  port: number;                    // SSH port (typically 22)
  username: string;                // SSH username
  password?: string;               // Password authentication
  privateKey?: string;             // Absolute path to private key file
  passphrase?: string;             // Passphrase for encrypted private key
                                   // Also reads from SSH_MCP_PASSPHRASE env var
  agent?: string;                  // SSH agent socket path ('pageant' for Windows)
  tryKeyboard?: boolean;           // Enable keyboard-interactive / 2FA (default: false)
                                   // 2FA code reads from SSH_MCP_2FA_CODE env var
  commandWhitelist?: string[];     // Regex patterns — command must match one to run
  commandBlacklist?: string[];     // Regex patterns — command must NOT match any
  socksProxy?: string;             // 'socks://user:pass@host:port'
  pty?: boolean;                   // Allocate pseudo-tty (default: true)
  allowedLocalPaths?: string[];    // Extra local dirs allowed for SFTP transfers
  allowedRemotePaths?: string[];   // Absolute POSIX paths allowed for SFTP
  transportMode?: "exec" | "shell"; // default: "exec"
  shellReadyTimeoutMs?: number;    // Shell init timeout (default: 10000)
  shellCommandTimeoutMs?: number;  // Per-command timeout in shell mode (default: 30000)
  commandTemplate?: string;        // Wrap commands: must contain '<command>'
}
```

// Full example — production server with all security options
const prodConfig: SSHConfig = {
  name: "prod",
  host: "10.0.0.2",
  port: 22,
  username: "deploy",
  privateKey: "/home/deploy/.ssh/id_ed25519",
  passphrase: process.env.SSH_MCP_PASSPHRASE,
  commandWhitelist: ["^ls( .*)?$", "^cat ", "^tail -f ", "^journalctl "],
  commandBlacklist: ["^rm -rf", "^dd ", "^mkfs"],
  allowedLocalPaths: ["/home/deploy/releases"],
  allowedRemotePaths: ["/var/www/html", "/tmp/deploy"],
  transportMode: "exec",
  pty: true,
};

```

--------------------------------

### Upload a local file to the remote server via SFTP

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Transfers a local file to the remote server using SFTP. Ensure local and remote paths comply with configured restrictions. Not available in shell transport mode.

```json
// Upload a deployment artifact
{
  "tool": "upload",
  "params": {
    "localPath": "./dist/app.tar.gz",
    "remotePath": "/var/www/releases/app.tar.gz",
    "connectionName": "prod"
  }
}
```

```json
// Success response
"File uploaded successfully"
```

```json
// Error: path traversal attempt
{
  "code": "LOCAL_PATH_NOT_ALLOWED",
  "message": "Path traversal detected. Local path must be within the working directory or configured allowed local paths.",
  "retriable": false
}
```

```json
// Error: remote path not in allowedRemotePaths
{
  "code": "REMOTE_PATH_NOT_ALLOWED",
  "message": "Remote path is not within the configured allowedRemotePaths.",
  "retriable": false
}
```

```json
// Error: shell mode
{
  "code": "UNSUPPORTED_IN_SHELL_MODE",
  "message": "Current bastion shell mode does not support SFTP upload/download.",
  "retriable": false
}
```

--------------------------------

### Download a file from the remote server via SFTP

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Transfers a file from the remote server to the local filesystem using SFTP. Subject to the same path restrictions as upload. Not available in shell transport mode.

```json
// Download a log file
{
  "tool": "download",
  "params": {
    "remotePath": "/var/log/nginx/access.log",
    "localPath": "./logs/access.log",
    "connectionName": "prod"
  }
}
```

```json
// Success response
"File downloaded successfully"
```

```json
// Error: local write failure
{
  "code": "LOCAL_FILE_WRITE_FAILED",
  "message": "Failed to save file: EACCES: permission denied, open './logs/access.log'",
  "retriable": false
}
```

```json
// Error: SFTP read failure on remote
{
  "code": "SFTP_ERROR",
  "message": "File download failed: No such file",
  "retriable": true
}
```

--------------------------------

### Execute Command on Remote Server

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Run a shell command on an SSH server and retrieve its standard output. Handles non-zero exit codes and signals with structured error responses.

```json
// Basic command execution
{
  "tool": "execute-command",
  "params": {
    "cmdString": "df -h",
    "connectionName": "prod"
  }
}

// With working directory and timeout
{
  "tool": "execute-command",
  "params": {
    "cmdString": "npm run build",
    "directory": "/var/www/myapp",
    "connectionName": "dev",
    "timeout": 120000
  }
}

// Long-running command with custom timeout (prevents indefinite hang)
{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 5 8.8.8.8",
    "connectionName": "prod",
    "timeout": 10000
  }
}

// Error response shape (isError: true)
{
  "code": "COMMAND_EXECUTION_ERROR",
  "message": "ls: cannot access '/nonexistent': No such file or directory\n[exit code] 2",
  "retriable": false
}

// Timeout error shape
{
  "code": "COMMAND_TIMEOUT",
  "message": "[timeout] Command timed out after 5000ms",
  "retriable": true
}

// Validation failure (command not in whitelist)
{
  "code": "COMMAND_VALIDATION_FAILED",
  "message": "Command validation failed: Command not in whitelist, execution forbidden",
  "retriable": false
}
```

--------------------------------

### SSHConfig Interface Definition

Source: https://context7.com/classfang/ssh-mcp-server/llms.txt

Defines all connection options for SSH. Use this interface to configure connection parameters like host, port, username, and authentication methods.

```typescript
interface SSHConfig {
  name?: string;                   // Connection name (required for multi-connection)
  host: string;                    // SSH server hostname or IP
  port: number;                    // SSH port (typically 22)
  username: string;                // SSH username
  password?: string;               // Password authentication
  privateKey?: string;             // Absolute path to private key file
  passphrase?: string;             // Passphrase for encrypted private key
                                   // Also reads from SSH_MCP_PASSPHRASE env var
  agent?: string;                  // SSH agent socket path ('pageant' for Windows)
  tryKeyboard?: boolean;           // Enable keyboard-interactive / 2FA (default: false)
                                   // 2FA code reads from SSH_MCP_2FA_CODE env var
  commandWhitelist?: string[];     // Regex patterns — command must match one to run
  commandBlacklist?: string[];     // Regex patterns — command must NOT match any
  socksProxy?: string;             // 'socks://user:pass@host:port'
  pty?: boolean;                   // Allocate pseudo-tty (default: true)
  allowedLocalPaths?: string[];    // Extra local dirs allowed for SFTP transfers
  allowedRemotePaths?: string[];   // Absolute POSIX paths allowed for SFTP
  transportMode?: "exec" | "shell"; // default: "exec"
  shellReadyTimeoutMs?: number;    // Shell init timeout (default: 10000)
  shellCommandTimeoutMs?: number;  // Per-command timeout in shell mode (default: 30000)
  commandTemplate?: string;        // Wrap commands: must contain '<command>'
}
```

--------------------------------

### Specify Custom SSH Config File Path

Source: https://github.com/classfang/ssh-mcp-server/blob/main/README.md

Allows overriding the default SSH configuration file path by providing a custom path via the `--ssh-config-file` argument. This is useful for managing multiple SSH configurations.

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}
```