mcp-ssh-tool

GitHub Copilot 및 VS Code를 위한 자율적인 SSH 작업을 제공하는 모델 컨텍스트 프로토콜(MCP) SSH 클라이언트 서버입니다. 수동 프롬프트나 GUI 상호 작용 없이 자연어로 SSH 자동화를 활성화하세요.

공식 MCP 레지스트리 항목: io.github.oaslananka/mcp-ssh-tool
레지스트리 메타데이터: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

빠른 시작

설치

• 전역 설치(권장): npm install -g mcp-ssh-tool

• 일회성 실행: npx mcp-ssh-tool

MCP 클라이언트 구성 (VS Code / Claude Desktop / 기타)

MCP 구성(mcp.json, .vscode/mcp.json 또는 Claude Desktop MCP 구성)에 추가하세요:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

사용 예시

구성 후에는 MCP 클라이언트에서 자연어를 사용할 수 있습니다:

• SSH 연결: "SSH 키를 사용하여 admin으로 서버 192.168.1.100에 연결해줘"

• 파일 작업: "서버의 /etc/nginx/nginx.conf 내용을 읽어줘"

• 명령 실행: "원격 서버에서 'systemctl status nginx'를 실행해줘"

• 패키지 관리: "Ubuntu 서버에 htop 패키지를 설치해줘"

• 서비스 제어: "nginx 서비스를 재시작해줘"

• Claude Desktop: "내 서버에 연결해서 디스크 사용량을 확인해줘"

• 패키지/서비스 스택 설치: "내 원격 서버에 nginx를 설치해줘"

• 설정 파일 읽기: "/etc/nginx/nginx.conf 파일을 읽어줘"

• 서비스 재시작: "nginx 서비스를 재시작해줘"

• 로그 탐색: "/var/log에 있는 파일 목록을 보여줘"

사용 가능한 도구

• ssh_open_session - 다양한 인증 방법을 사용하여 SSH 연결 설정

• ssh_close_session - SSH 세션 종료

• ssh_list_sessions - 모든 활성 SSH 세션 나열

• ssh_ping - 세션이 활성 상태이고 응답하는지 확인

• ssh_list_configured_hosts - ~/.ssh/config에서 호스트 나열

• ssh_resolve_host - SSH 구성에서 호스트 별칭 확인

• proc_exec - 원격으로 명령 실행 (선택적 타임아웃 포함)

• proc_sudo - sudo 권한으로 명령 실행

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename - 파일 시스템 작업

• ensure_package - present 및 absent 상태를 사용한 패키지 관리

• ensure_service - restarted를 포함한 서비스 제어

• ensure_lines_in_file - present 및 absent 상태를 사용한 파일 라인 관리

• patch_apply - 파일에 패치 적용

• os_detect - 시스템 정보 감지

• get_metrics - JSON 또는 Prometheus 형식의 서버 메트릭

• proc_exec_stream - 청크 단위 출력으로 스트리밍 명령 실행

• file_upload, file_download - SFTP 파일 전송 도우미

• tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list - 터널 관리

사용 가능한 리소스

• mcp-ssh-tool://sessions/active - JSON 형식의 활성 세션

• mcp-ssh-tool://metrics/json - JSON 형식의 메트릭 스냅샷

• mcp-ssh-tool://metrics/prometheus - Prometheus 메트릭 내보내기

• mcp-ssh-tool://ssh-config/hosts - 파싱된 로컬 SSH 호스트 별칭

개요

SSH MCP 서버는 GitHub Copilot과 SSH를 통한 원격 시스템 간의 가교 역할을 합니다. 다음을 지원합니다:

• 비대화형 SSH 작업 - 프롬프트나 GUI 상호 작용 없음

• 다중 인증 방법 - 비밀번호, SSH 키 또는 SSH 에이전트

• 세션 관리 - TTL 및 LRU 제거를 통한 자동 연결 풀링

• 파일 시스템 작업 - SFTP를 통한 원격 파일 읽기, 쓰기, 나열 및 관리 (SFTP 하위 시스템을 노출하지 않는 호스트의 경우 SSH 셸로 대체)

• 프로세스 실행 - 원격으로 명령 및 sudo 작업 실행

• 고수준 자동화 - 패키지 관리, 서비스 제어 및 구성 관리

• 보안 - 로그 내 민감한 데이터 자동 삭제

아키텍처

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

임베디드 / BusyBox 대상

일부 임베디드 대상은 SSH 명령 실행을 노출하지만 SFTP 하위 시스템을 제공하지 않는데, 이는 Dropbear 또는 BusyBox 기반 시스템에서 흔히 볼 수 있습니다. 이 경우 ssh_open_session은 여전히 성공하며 sftpAvailable: false를 보고합니다. fs_read, fs_write, fs_stat, fs_list, fs_mkdirp, fs_rmrf, fs_rename과 같은 핵심 파일 도구는 자동으로 셸 기반 구현으로 대체됩니다.

설치

사전 요구 사항

• Node.js ≥ 20 (LTS)

• 대상 시스템에 대한 SSH 액세스

• 인증을 위한 SSH 키 또는 자격 증명

npm에서 설치

npm install -g mcp-ssh-tool

소스에서 빌드

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

CLI 플래그

• --help / -h: 사용법 및 예시 표시.

• --version / -v: 버전 출력.

• --stdio: stdio 모드 강제 (기본값).

참고: 이것은 MCP stdio 서버입니다. 터미널은 대화형 셸이 아니므로 MCP 클라이언트(Claude Desktop, VS Code MCP 등)를 사용하거나 stdio를 통해 JSON-RPC를 보내십시오.

플랫폼 참고 사항

• Linux / macOS: 안전한 인용과 함께 POSIX 셸 래퍼를 사용합니다. 기본 임시 디렉터리: /tmp.

• Windows 대상: OpenSSH 서버/에이전트가 필요합니다. 키 검색은 C:\Users\<사용자>\.ssh\를 확인합니다. 명령은 PowerShell에서 안전하게 실행되도록 래핑됩니다. 패키지/서비스 도우미는 Windows 대상에서 의도적으로 비활성화되어 있습니다.

• 호스트 키: 호스트 키 확인은 기본적으로 완화되어 있습니다. STRICT_HOST_KEY_CHECKING=true 및 선택적으로 KNOWN_HOSTS_PATH를 설정하여 확인을 강제할 수 있습니다.

ChatGPT Desktop 통합

빠른 설정

npm run setup:chatgpt

이 명령은 ChatGPT Desktop이 mcp-ssh-tool을 사용하도록 자동으로 구성합니다.

수동 설정

ChatGPT Desktop MCP 구성에 추가하세요:

• macOS: ~/Library/Application Support/ChatGPT/mcp.json

• Windows: %APPDATA%\ChatGPT\mcp.json

• Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

자세한 사용법은 docs/chatgpt-usage.md를 참조하세요.

Codex 통합

빠른 설정

패키지를 전역으로 설치한 다음 Codex에 등록하세요:

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

전역 설치를 원하지 않는 경우 npx를 통해 등록할 수 있습니다:

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

확인

Codex가 MCP 서버를 볼 수 있는지 확인하세요:

codex mcp list
codex mcp get ssh-mcp

명령이 mcp-ssh-tool 또는 npx인 활성화된 stdio 서버가 보여야 합니다.

선택적 보안 강화

Codex 관리 서버 프로세스에서 호스트 키 확인을 강제하려면:

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

서버를 추가한 후 Codex를 다시 시작하거나 새 세션을 열고, 활성 세션 나열이나 SSH 연결 열기와 같은 간단한 도구 호출을 시도해 보세요.

VS Code Copilot 통합

사용자 수준 구성 (권장)

VS Code를 열고 Ctrl+Shift+P를 누른 다음 **"MCP: Open User Configuration"**을 실행하세요.

mcp.json에 추가하세요:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

작업 영역 수준 구성

작업 영역에 .vscode/mcp.json을 만드세요:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

확인

1. VS Code 다시 시작

2. Copilot Chat 열기

3. SSH MCP 도구가 사용 가능한 도구 목록에 나타나야 함

4. 다음으로 테스트: "192.168.1.100에 admin으로 연결해서 'uname -a'를 실행해줘"

Claude Desktop, Antigravity 및 기타 MCP 클라이언트

stdio 서버를 실행할 수 있는 모든 MCP 호환 클라이언트는 mcp-ssh-tool을 사용할 수 있습니다. 정확한 설정 화면이나 구성 파일은 클라이언트마다 다르지만 프로세스는 동일합니다:

1. 패키지 설치:

npm install -g mcp-ssh-tool

2. 다음을 실행하는 stdio MCP 서버 등록:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

3. 클라이언트가 servers 대신 mcpServers 스타일 스키마를 사용하는 경우 해당 항목을 사용하세요:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Claude Desktop의 경우 MCP 구성에서 위의 stdio 명령 패턴을 사용하세요. Antigravity나 다른 MCP 클라이언트의 경우 클라이언트 자체의 MCP 설정 UI나 구성 형식을 사용하되, 동일한 실행 명령을 가리키도록 하세요.

사용 예시

기본 연결 및 명령 실행

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

파일 작업

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

시스템 관리

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

구성 관리

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

바로 사용할 수 있는 프롬프트 아이디어

"connect to my server and check disk usage"

"install nginx on my remote server"

"read the file /etc/nginx/nginx.conf"

"restart the nginx service"

"list files in /var/log"

전문가 팁

• 다중 세션: 호스트나 환경당 하나의 세션을 열고 프로덕션, 스테이징, 개발 머신 간을 전환할 때 ssh_list_sessions 및 ssh_ping으로 세션을 활성 상태로 유지하세요.

• BusyBox/Dropbear용 SFTP 대체: SFTP 하위 시스템을 노출하지 않는 임베디드 시스템에서 ssh_open_session은 sftpAvailable: false로 성공할 수 있으며, 핵심 fs_* 도구는 자동으로 셸 기반 구현으로 대체됩니다.

• 호스트 키 확인: 더 엄격한 프로덕션급 SSH 확인을 위해 MCP 서버 환경에서 STRICT_HOST_KEY_CHECKING=true를 설정하고 선택적으로 KNOWN_HOSTS_PATH를 설정하세요.

API 참조

아키텍처

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

새 도구 그룹 추가

1. ToolProvider를 구현하는 src/tools/<your-namespace>.provider.ts 생성

2. src/tools/index.ts에 등록

3. test/unit/tools/<your-namespace>.provider.test.ts에 단위 테스트 추가

mcp.ts를 변경할 필요는 없습니다.

세션 도구

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

반환값:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• ssh_list_sessions는 남은 TTL과 함께 활성 세션을 반환합니다.

• ssh_ping은 세션의 활성 상태와 지연 시간을 확인합니다.

• ssh_list_configured_hosts는 ~/.ssh/config를 읽습니다.

• ssh_resolve_host는 SSH 호스트 별칭을 연결 매개변수로 확장합니다.

명령 도구

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

둘 다 다음을 반환합니다:

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

파일 도구

• fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

• fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

• fs_stat은 size, mtime, mode, type을 반환합니다.

• fs_list는 { "entries": [...], "nextToken": "optional" }을 반환합니다.

• fs_mkdirp는 디렉터리를 재귀적으로 생성합니다.

• fs_rmrf는 파일이나 디렉터리를 재귀적으로 삭제합니다.

• fs_rename은 경로를 이름 변경하거나 이동합니다.

구성 및 자동화 도구

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state는 present 및 absent를 지원합니다.

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state는 started, stopped, restarted, enabled, disabled를 지원합니다.

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state는 present 및 absent를 지원합니다.

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

원격 플랫폼, 배포판, 버전, 패키지 관리자, init 시스템, 셸 및 임시 디렉터리를 반환합니다.

get_metrics

서버 메트릭을 반환합니다. 기본 출력은 JSON이며, 선택적 { "format": "prometheus" }는 Prometheus 텍스트 형식을 출력합니다.

인증

서버는 자동 대체 기능을 갖춘 다중 인증 방법을 지원합니다:

인증 전략 우선순위

1. 비밀번호 (제공된 경우)

2. SSH 키 (인라인 → 경로 → 자동 검색)

3. SSH 에이전트 (사용 가능한 경우)

SSH 키 자동 검색

서버는 다음 위치에서 SSH 키를 자동으로 검색합니다:

• ~/.ssh/id_ed25519

• `