Skip to main content
Glama
NHN Server MCP
by dhks77

gw-ssh

A CLI tool for executing commands and transferring files to remote servers via an SSH Gateway.

Features

  • Remote server command execution via SSH Gateway (real-time streaming output)

  • Parallel execution on multiple hosts (single Gateway authentication + internal fan-out)

  • SCP file upload/download via Gateway (binary integrity guaranteed)

  • Kerberos authentication (kinit) support

  • Prevents process hangs with remote command timeouts

  • Access restriction via host allowlist

Related MCP server: SSH MCP Server

Installation

npm install
npm run build
npm link        # gw-ssh 명령어 글로벌 등록

Configuration

Create config.json

{
  "gatewayConnection": "user@gateway.example.com:22",
  "gatewayPassword": "your-password",
  "kinitPassword": "your-kerberos-password",
  "allowedHosts": ["server1", "server2"],
  "commandTimeoutSec": 300,
  "serverInfo": {
    "user": "default-ssh-user",
    "logPaths": {
      "app": "/var/log/app"
    }
  }
}

Specify configuration file path

# 방법 1: 환경변수 (~/.zshrc 등에 추가)
export CONFIG_FILE=/path/to/config.json

# 방법 2: --config 옵션
gw-ssh -c /path/to/config.json <command>

Configuration Options

Key

Description

Default

gatewayConnection

Gateway SSH connection (user@host:port)

Required

gatewayPassword

Gateway SSH password

Required

kinitPassword

Kerberos authentication password (skips kinit if not set)

-

allowedHosts

List of allowed hosts

[] (allow all)

commandTimeoutSec

Remote command timeout (seconds). Wrapped with GNU timeout

300

serverInfo

Server meta information (user, logPaths, etc.)

{}

Environment Variables

Variable

Description

CONFIG_FILE

Path to config.json file

DEBUG

Enable debug logs (true/false)

Usage

Command Execution

gw-ssh exec <host> <command> [-u user] [-j jobs] [--buffered]
# 단일 호스트
gw-ssh exec server1 "hostname"
gw-ssh exec server1 "uptime" -u appuser

# 로그 조회
gw-ssh exec server1 "tail -100 /var/log/app/app.log"
gw-ssh exec server1 "grep ERROR /var/log/app/app.log | tail -20"

If -u is omitted, the serverInfo.user value is used.

Parallel execution on multiple hosts

If you pass a comma-separated CSV to <host>, it automatically operates in parallel mode. Gateway authentication/Kerberos ticket is performed only once, and fan-out occurs in the gateway→target segment.

# 3개 호스트에서 동시에 실행 (기본 동시성 5)
gw-ssh exec server1,server2,server3 "hostname && uptime"
# [server1] server1
# [server1]  15:02:31 up 42 days, ...
# [server2] server2
# [server2]  15:02:31 up 12 days, ...
# [server3] server3
# [server3]  15:02:31 up  7 days, ...
# ✓ 3/3 성공

# 동시성 제한 변경 (gateway 부하 고려해 3~10 권장)
gw-ssh exec h1,h2,h3,h4,h5,h6,h7,h8 "uptime" -j 10

# 호스트별로 출력을 모아 순서대로 표시 (스트리밍 대신 버퍼드 모드)
gw-ssh exec h1,h2 "cat /etc/hostname" --buffered

If some hosts fail, a failure summary is printed to stderr with exit code 1.

File Upload

gw-ssh upload <host> <remotePath> [options] [-u user] [-j jobs]
# 텍스트 내용 직접 업로드
gw-ssh upload server1 /tmp/hello.txt --content "hello world"

# 로컬 파일 업로드 (바이너리 포함 - gzip, zip, 실행파일 등)
gw-ssh upload server1 /tmp/app.tar.gz --file ./app.tar.gz

# 여러 호스트에 같은 파일 동시 배포 (CSV 지정 시 병렬 모드)
gw-ssh upload server1,server2,server3 /tmp/app.tar.gz --file ./app.tar.gz

When uploading to multiple hosts, the local→gateway transfer occurs once, and gateway→each target is fanned out in parallel. The larger the file or the more hosts, the greater the local bandwidth savings.

File Download

gw-ssh download <host> <remotePath> [options] [-u user] [-j jobs]
# 표준 출력으로 내용 확인
gw-ssh download server1 /etc/hosts

# 로컬 파일로 저장
gw-ssh download server1 /etc/hosts -o ./downloaded-hosts.txt

# 바이너리 파일도 무결성 유지 (gzip, zip, 실행파일 등)
gw-ssh download server1 /var/app/release.tar.gz -o ~/Downloads/release.tar.gz

# 여러 호스트에서 동시에 다운로드 — -o 에 디렉토리 지정, 파일명 앞에 호스트 접두
gw-ssh download server1,server2 /var/log/app.log -o ~/Downloads/
# → ~/Downloads/server1-app.log
# → ~/Downloads/server2-app.log

-o must be a file path for a single host, or an already existing directory path for multiple hosts.

In multi-host downloads, if only some hosts fail, the files from the successful hosts remain in the -o directory. Manual deletion is required if a full rollback is needed.

Check Configuration

gw-ssh config

Connection Test

gw-ssh status

Security

  • Do not commit config.json to git as it contains sensitive information (passwords)

  • Restrict accessible servers with allowedHosts

  • Command safety ensured with Base64 encoding + shell injection prevention patterns

  • Automatic SSH session cleanup even when exceptions occur

License

MIT

Available Tools

5 tools
connection_statusB

현재 SSH 연결 상태를 확인합니다.

Inputs: no named parameters.

disconnect_serverB

Gateway 연결을 종료합니다.

Inputs: no named parameters.

execC

서버에서 명령어를 실행합니다.

Inputs: host (required), user (required), command (required).

get_configB

서버 설정 정보를 조회합니다. 허용된 호스트, 명령어, 서버 정보 등을 확인할 수 있습니다.

Inputs: no named parameters.

reload_configA

서버 설정을 다시 로드합니다. SERVER_INFO_FILE 등이 변경되었을 때 사용합니다.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: connection_status checks SSH status, disconnect_server terminates connections, exec runs commands, get_config retrieves settings, and reload_config reloads configurations. The descriptions reinforce these distinct roles, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., connection_status, disconnect_server, exec, get_config, reload_config). This uniformity enhances readability and predictability across the set.

    Tool Count5/5

    With 5 tools, this server is well-scoped for managing SSH connections and server configurations. Each tool earns its place by covering essential operations like status checks, command execution, and configuration handling without being overly sparse or bloated.

    Completeness4/5

    The tool set provides strong coverage for SSH and server management, including status, disconnection, command execution, and configuration operations. A minor gap exists in lacking a tool for initiating or establishing new SSH connections, but agents can work around this using exec or other methods.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      Enables secure SSH connections to remote servers for executing shell commands and managing active sessions. It supports authentication via passwords or private keys and provides optional host-based access control.
      4
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables remote server administration via SSH, supporting command execution, SFTP file transfers, and multi-profile management. It features security safeguards like destructive command detection and audit logging to ensure safe interaction with remote Linux/Unix environments.
      17
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to execute SSH commands and transfer files via SFTP through a centralized HTTP gateway with per-client authorization, layered command policies, audit logging, rate limiting, circuit breakers, and connection pooling.
      9
      MIT