SSH MCP 서버 — AI 에이전트용 원격 서버 도구

이 서버는 여러분 머신에 이미 설치된 OpenSSH 클라이언트를 사용합니다: 여러분의 키, ~/.ssh/config, 점프 호스트, 에이전트 포워딩. 번들로 포함된 것도, 컴파일할 것도, 네이티브 바인딩도 없습니다.

Claude Code, Codex CLI, opencode, Gemini CLI, Qwen Code, Hermes 및 기타 MCP 클라이언트와 함께 작동합니다.

설치 · 도구 · 설정 · 보안 · 로드맵 · 문서 · 변경 이력

30초 설치

전역 설치가 필요 없습니다. npx가 첫 사용 시 패키지를 다운로드합니다:

npx -y @hypnosis/ssh-mcp-server

Claude Code에 모든 프로젝트에 대해 추가하세요:

claude mcp add ssh -s user \
  -e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

그런 다음 ~/.claude/ssh-profiles.json을 생성하고 최소 하나의 머신을 추가하세요:

{
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin",
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

이것으로 연결이 가능합니다.

Codex, opencode, Qwen Code 및 기타 클라이언트는 SSH MCP 서버 설정에서 다룹니다.

요구 사항

Node.js 18+ 및 PATH에 있는 시스템 ssh 클라이언트. Windows에서는 키 기반 프로필을 사용하세요; 비밀번호 및 패스프레이즈 프로필은 현재 지원되지 않습니다.

고정 버전을 선호하거나, 오프라인 작업을 하거나, 실행할 때마다 레지스트리 확인을 하나 줄이고 싶다면: npm install -g @hypnosis/ssh-mcp-server를 실행한 후 npx 대신 ssh-mcp-server를 명령으로 사용하세요.

Related MCP server: ssh-mcp-server

이런 분들을 위한 서버입니다

• DevOps 및 SRE — 더 빠른 감사(audit), 장애 점검, 일상적인 서버 작업을 원하는 분.

• 바이브 코더와 인디 빌더 — AI 어시스턴트와 함께 제품을 출시하고 자신의 서버에서 실행하는 분.

• 시스템 관리자와 플랫폼 엔지니어 — 제한 없는 원시 셸 대신 구조화된 도구를 원하는 분.

• 전담 운영 팀 없이 자체 VPS를 운영하는 개발자와 소규모 팀.

• 홈랩, NAS, 라우터 소유자 — 유용한 하드웨어가 현대 프로토콜을 지원하지 못하는 분.

원시 셸 대신 SSH MCP 서버를 사용하는 이유

더 적은 토큰, 더 낮은 AI 비용

원시 셸은 AI 에이전트에게 화재 호스를 쏟아붓습니다: 반복되는 명령, ASCII 테이블, 로그 덤프. 그 노이즈를 서버 상태 파악으로 바꾸는 데 토큰이 소모됩니다 — 바로 여러분의 비용입니다.

더 빠른 서버 디버깅

목적에 맞게 설계된 도구는 일상적인 점검을 일괄 처리하고, 시끄러운 출력을 제한하며, 중요한 부분만 반환합니다. 에이전트는 터미널 출력을 해석하는 데 시간을 덜 쓰고 더 빨리 수정에 도달합니다.

더 적은 추측, 더 적은 AI 실수

구조화된 응답은 무엇이 발견되었는지, 무엇을 측정할 수 없었는지, 무엇이 잘렸는지를 명확히 말합니다. 이는 에이전트가 환각으로 빈틈을 메울 여지를 줄여줍니다 — 그리고 더 적은 잘못된 수정, 더 안정적인 배포, 더 신뢰할 수 있는 코드를 제공합니다.

SSH 호환성: 최신 서버, 레거시 장비, Windows

기존 OpenSSH 설정 활용

번들 SSH 구현도, 네이티브 바인딩도, 플랫폼별 재빌드도 없습니다. 명령은 시스템 ssh 클라이언트를 사용하므로 여러분의 키, ~/.ssh/config, 점프 호스트, 에이전트 포워딩이 터미널에서와 똑같이 작동합니다. 지원되는 경우, 대상별로 공유된 멀티플렉스 연결 하나를 사용하여 명령마다 인증하는 대신 한 번만 인증합니다.

레거시 서버, 라우터, NAS 기기용 SSH 지원

최신 scp로 라우터에 파일을 보내면 이런 결과가 나옵니다:

scp app.conf router:/etc/
# scp: subsystem request failed on channel 0

아무것도 고장난 것이 아닙니다 — 현재 scp는 새 프로토콜을 사용하며 라우터는 그것을 모릅니다. 터미널에서는 포럼 스레드를 읽고 추가 플래그를 들고 돌아와야 합니다. 여기서는 아무것도 할 필요가 없습니다: 전송이 시도되고, 거부가 인식되며, 이전 프로토콜이 대신 사용되고, 해당 머신이 기억되어 다음 파일은 바로 그 프로토콜로 전송됩니다.

구형 SSH 클라이언트 및 누락된 도구에 대한 폴백

구형 장비에는 막다른 길이 아닌 폴백이 제공됩니다. 최신 기능이 없을 때 서버는 가능한 경우 이전 방식을 사용합니다:

Model Context Protocol을 위해 설계됨

공식 MCP SDK 기반, 전체 TypeScript, 2500개 이상의 단위 테스트와 실제 컨테이너에서 실행되는 라이브 테스트 스위트(모의 객체가 아닌)를 갖추고 있습니다.

원시 SSH vs SSH MCP 서버: 같은 작업, 두 가지 방식

SSH 서버 상태 점검

상황: 배포가 막 완료되었습니다. 서버가 느려진 것 같지만 디스크, 메모리, 서비스, 컨테이너, 오류 중 무엇이 원인인지 모릅니다.

질문: "이 서버는 정상인가요?"

원시 SSH

$ uptime
 10:42:17 up 18 days,  3:21,  2 users,  load average: 0.42, 0.31, 0.28
$ df -hT
Filesystem     Type   Size  Used Avail Use% Mounted on
/dev/sda1      ext4    40G   35G  5.0G  87% /
overlay        overlay  40G   35G  5.0G  87% /var/lib/docker/overlay2/...
$ free -h
               total        used        free      shared  buff/cache   available
Mem:           7.7Gi       4.9Gi       612Mi       121Mi       2.2Gi       2.5Gi
$ systemctl --failed
  UNIT              LOAD   ACTIVE SUB    DESCRIPTION
● api-worker.service loaded failed failed API background worker
$ docker ps -a
CONTAINER ID   IMAGE          STATUS                     PORTS
8e14d0b41c2a   api:latest     Up 3 minutes               0.0.0.0:8080->8080/tcp
65b894af2430   worker:latest  Exited (1) 2 minutes ago
$ ss -tulpn
Netid  State   Local Address:Port   Process
tcp    LISTEN  0.0.0.0:22          users:(("sshd",pid=842,fd=3))
tcp    LISTEN  0.0.0.0:8080        users:(("docker-proxy",pid=1942,fd=4))
$ journalctl -p err --since -1h | tail -50
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
Aug 20 10:39:14 prod systemd[1]: api-worker.service: Failed with result 'exit-code'.

이것도 여전히 축약된 결과입니다. 완전한 점검에는 CPU, 서비스 상태, 컨테이너 수, 최근 오류에 대한 더 많은 명령이 필요하며 각각 고유한 출력 형식을 가집니다. 더 나쁜 것은, ss가 없는 서버는 포트 점검이 실행되지 않았는데도 수신 대기 중인 것이 0개인 것처럼 보일 수 있습니다.

구조화된 MCP 결과

ssh_snapshot({ "profile": "production" })

{
  "disk_pct": 87,
  "mem_pct": 64,
  "cpu_pct": 12,
  "load": "0.42 0.31 0.28",
  "containers": 7,
  "ports": 14,
  "services_running": 3,
  "recent_errors": 21,
  "unavailable": []
}

에이전트가 얻는 이점

전체 ssh_audit_baseline 결과는 소수의 원시 명령 출력보다 길 수 있습니다 — 실험실 측정에서 약 1,077 토큰 대 765 토큰. 절약은 하나의 응답을 더 짧게 만드는 것이 아니라 전체 워크플로우에서 발생합니다.

실제 트러블슈팅 세션에서 목적에 맞게 설계된 도구는 49개의 개별 명령 호출을 4개의 MCP 호출로 줄였습니다. 추가 호출마다 누적된 대화와 함께 새로운 모델 턴이 시작됩니다. 프롬프트 캐싱은 반복 입력 비용을 줄일 수 있지만, 새 명령과 그 출력은 여전히 컨텍스트를 소비합니다. 더 적은 왕복은 세션 전체에서 더 적은 토큰, 더 적은 반복 분석, 그리고 답에 도달하는 더 빠른 경로를 의미합니다.

맥박이 아닌 전체 그림이 필요하신가요? ssh_audit_baseline은 시스템, 디스크, 메모리, 포트, sshd, 실패한 유닛, Docker, 방화벽, 업데이트를 일괄 처리합니다. 결과는 CRITICAL / WARNING / OK로 제공됩니다. 측정되지 않은 섹션은 0으로 조용히 읽히는 대신 명시적으로 이름이 지정됩니다.

Linux 서버 로그 검색

상황: API가 타임아웃되고 있지만, 같은 메시지가 nginx, syslog, journald 또는 일반 사용자로 읽을 수 없는 애플리케이션 로그에 있을 수 있습니다.

질문: "그 오류는 어디서 발생한 건가요?"

원시 SSH

$ grep -i "timeout" /var/log/nginx/error.log
2026/08/20 10:38:54 [error] upstream timed out while reading response header
$ grep -i "timeout" /var/log/syslog
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
$ grep -i "timeout" /var/log/app/*.log 2>/dev/null
$ journalctl -u api --since "1 hour ago" | grep -i timeout
Aug 20 10:39:14 prod api[22104]: database connection timed out after 30000ms

세 번째 명령은 깔끔해 보이지만, 2>/dev/null이 권한 오류도 숨겼습니다. "일치하는 항목 없음"과 "읽은 항목 없음"이 이제 동일하게 보입니다. 바쁜 로그는 수천 줄을 반환하여 사고의 나머지 부분을 에이전트의 컨텍스트 밖으로 밀어낼 수도 있습니다.

구조화된 MCP 결과

ssh_log_search({ "profile": "production",
                 "path": ["/var/log/nginx/error.log", "/var/log/syslog", "/var/log/app/*.log"],
                 "query": "timeout", "context": 2, "since": "1h" })

{
  "matches": 34,
  "lines": [
    { "file": "/var/log/nginx/error.log", "line": 4821,
      "text": "upstream timed out while reading response header", "context": false },
    { "file": "/var/log/nginx/error.log", "line": 4822,
      "text": "client closed connection", "context": true }
  ],
  "files_searched": 6,
  "files_unreadable": ["/var/log/app/private"],
  "files_skipped": 12,
  "files_undated": [],
  "limited": false,
  "truncated": false
}

에이전트가 얻는 이점

since는 서버의 시계를 사용하고, namesOnly: true는 일치하는 경로만 반환하며, ssh_log_tail은 한 번의 호출로 여러 로그의 마지막 N줄을 읽습니다.

안전한 원격 설정 파일 편집

상황: 운영 중인 서버의 nginx 설정을 교체해야 합니다. 연결 끊김, 잘못된 모드, 확인되지 않은 복사는 서비스를 손상된 파일로 남길 수 있습니다.

질문: "부분 파일을 남기지 않고 이 설정을 교체할 수 있나요?"

원시 SSH

$ sudo sh -c 'cat > /etc/nginx/conf.d/api.conf' <<'EOF'
server {
    listen 80;
    location / { proxy_pass http://127.0.0.1:8080; }
}
EOF
$ echo $?
0

종료 코드 0은 셸이 완료되었음을 의미합니다. 어떤 바이트가 실제로 기록되었는지는 증명하지 않으며, >는 새 파일의 첫 바이트가 도착하기 전에 기존 파일을 잘라버렸습니다. 쓰기 중에 연결이 끊기면 서비스는 부분 설정 파일을 남기게 됩니다.

구조화된 MCP 결과

ssh_file_write({ "profile": "production",
                 "files": [{ "path": "/etc/nginx/conf.d/api.conf",
                             "content": "server {\n    listen 80;\n    location / { proxy_pass http://127.0.0.1:8080; }\n}\n",
                             "mode": "644", "sudo": true, "verify": true }] })

{
  "files": [{ "path": "/etc/nginx/conf.d/api.conf", "written": true,
              "verified": "verified", "reason": null, "bytes": 79 }]
}

에이전트가 얻는 이점

verified는 세 가지 정직한 결과를 가집니다: verified, 서버에 해시 도구가 없을 때의 unavailable, 그리고 검증이 요청되지 않았을 때의 skipped입니다. 읽기의 경우 ssh_file_read는 경로 목록을 받고, ssh_file_list는 glob, 재귀, 크기, 모드를 처리합니다.

sudo로 배치 SSH 명령 실행하기

상황: 배포가 준비됐지만, 트래픽을 이동하기 전에 nginx 문법, 서비스 상태, 최근 오류를 모두 확인해야 합니다. 한 번의 실패한 검사가 결합된 덤프 안에서 사라져서는 안 됩니다.

질문: "모든 사전 점검이 통과했나요?"

원시 SSH

$ ssh admin@server.example.com 'sudo nginx -t'
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ ssh admin@server.example.com 'sudo systemctl is-active nginx'
active
$ ssh admin@server.example.com 'sudo tail -5 /var/log/nginx/error.log'
2026/08/20 10:38:54 [error] upstream timed out while reading response header

세 번의 연결이 서로 무관한 세 가지 출력을 반환합니다. 명령을 ;로 연결하면 쉘은 마지막 종료 코드만 보고하고, &&로 연결하면 첫 실패 이후의 검사는 사라집니다.

구조화된 MCP 결과

ssh_exec({ "profile": "production",
           "command": ["nginx -t", "systemctl is-active nginx",
                       "tail -5 /var/log/nginx/error.log"],
           "sudo": true })

{
  "commands": [
    { "command": "nginx -t", "exit_code": 0, "truncated": false, "clipped_bytes": 0,
      "stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n" },
    { "command": "systemctl is-active nginx", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "active\n", "stderr": "" },
    { "command": "tail -5 /var/log/nginx/error.log", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "2026/08/21 09:14:02 [error] upstream timed out\n", "stderr": "" }
  ],
  "job_id": null
}

에이전트가 얻는 이점

파괴적 명령 가드는 첫 번째 명령이 실행되기 전에 전체 목록을 검사합니다. 하나의 항목이 거부되면 다른 모든 항목은 실행되지 않은 것으로 표시되고 서버로 아무것도 전송되지 않습니다.

각 명령은 자체 stdout과 stderr를 가집니다. 실행되어 출력이 없는 명령은 빈 문자열을 가지며, 실행되지 않은 명령은 해당 필드가 아예 없으므로 둘을 혼동할 수 없습니다. 명령당 128KB를 초과하는 출력은 양쪽 끝을 모두 유지합니다 — 테이블용 머리와 로그용 꼬리 — 그리고 그 사이의 이음매는 잘린 양을 명시하며, clipped_bytes가 잘린 바이트 수를 알려줍니다. 잘림은 바이트 경계에서 발생하고 문자 끝으로 물러나므로, 잘린 출력에 교체 표시가 포함되지 않습니다.

sudo는 터미널 없이 서버에 도달합니다: 프로필에 비밀번호가 있으면 표준 입력으로 sudo에 전달됩니다. 키로 인증하는 프로필에는 전달할 비밀번호가 없으므로, 거기서 sudo는 이미 비밀번호 없이 허용된 곳에서만 작동합니다. 그리고 자신의 표준 입력을 읽는 명령에는 비밀번호가 절대 전달되지 않으므로, 비밀번호가 데이터에 섞여 들어가지 않습니다.

장기 실행 SSH 작업 실행하기

상황: 백업이나 마이그레이션이 대화보다 오래 실행됩니다. 연결이 끊길 수 있지만, 나중에 상태, 출력, 종료 코드가 여전히 필요합니다.

질문: "이 작업이 대화가 끝난 뒤에도 유지될까요?"

원시 SSH

$ ssh admin@server.example.com 'pg_dump app | gzip > /srv/backups/app.sql.gz'
client_loop: send disconnect: Broken pipe

터미널이 닫혔습니다. 다시 연결해 프로세스를 찾고, 대상 파일을 조사하고, 백업이 완료됐는지 중간에 실패했는지 추측해야 합니다.

Structured MCP 결과

ssh_exec({ "profile": "production",
           "command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
           "detach": true })

{
  "commands": [{
    "command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
    "exit_code": null,
    "truncated": false,
    "timed_out": false,
    "blocked": false,
    "blocked_reason": null,
    "not_run": false,
    "warning": null
  }],
  "job_id": "mst0f2q1-9ab3c4d5"
}

얻을 수 있는 이점

작업 상태는 이 서버의 메모리가 아니라 원격 머신의 디스크에 저장됩니다. ssh_job_status는 running, finished, lost를 구분하며, ssh_job_output은 마지막 바이트 오프셋부터 이어서 읽고, ssh_job_kill은 셸뿐 아니라 전체 프로세스 그룹에 시그널을 보냅니다.

레거시 라우터와 NAS 장치로 파일 전송하기

상황: 현재 OpenSSH 클라이언트는 SFTP를 시도하지만, 라우터나 NAS는 기존의 scp 프로토콜만 이해합니다. 파일은 그래도 온전히 도착하고 대상 파일을 안전하게 교체해야 합니다.

질문: "이 오래된 장치가 여전히 검증된 파일을 받을 수 있을까요?"

원시 SSH

$ scp app.conf operator@router:/etc/app.conf
subsystem request failed on channel 0
scp: Connection closed

보통 다음 단계는 레거시 플래그를 기억해 내고, 재시도한 다음 별도의 해시 명령을 실행하는 것입니다 — 장치에 해시 도구가 있다면 말이죠.

구조화된 MCP 결과

ssh_upload({ "profile": "router", "local_path": "./app.conf",
             "remote_path": "/etc/app.conf", "sudo": true,
             "mode": "644", "owner": "root:root", "verify": true })

{
  "files": [{
    "path": "/etc/app.conf",
    "written": true,
    "verified": "verified",
    "reason": null,
    "bytes": 1284
  }]
}

에이전트가 얻는 이점

장치에 sha256sum도 openssl도 없으면 결과는 unavailable이라고 말하고, 잘못된 일치를 보고하는 대신 이유를 명시합니다. recursive: true로 재귀 전송을 하면 해시도 재귀적으로 검증합니다.

파괴적 명령 보호

이 서버는 사전 검사 없이 임의의 SSH 명령을 실행하지 않습니다. 파괴적 명령은 로컬에서 차단됩니다.

AI 에이전트를 위한 파괴적 명령 가드

가드는 로컬에서, 명령이 SSH로 전송되기 전에 실행됩니다. 데이터를 담고 있는 것을 지우는 작업과 내용만 바꾸는 작업을 구분하고, 명령 순서도 확인합니다.

파괴적 체인을 시작하기 전에 멈추기

안전한 교체 순서:

cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old && rm -rf /srv/app

같은 작업을 파괴적 순서로:

rm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old
# REFUSED before the first command runs

쉘은 백업 소스가 사라진 것을 나중에야 발견합니다. 가드는 이전 단계가 이미 파괴한 대상을 이후 단계가 읽는 것을 감지하고 전체 호출을 사용자 머신에 남겨 둡니다. 같은 검사가 && 체인에도 적용됩니다 — 예를 들어 dropdb app && pg_dump app > backup.sql은 pg_dump가 존재하지 않는 데이터베이스를 읽으려고 하므로 차단됩니다.

되돌릴 수 없는 손실은 거부하고, 경고만 하는 경우

명령이 파괴적인지 아닌지는 컨텍스트에 따라 다릅니다. rm -rf 한 줄만으로는 충분하지 않습니다. 가드는 경로 제한과 함께 전체 명령 목록을 확인합니다.

확인된 파괴적 명령

가드는 로컬에서, 명령이 SSH로 전송되기 전에 실행됩니다. 데이터를 담고 있는 것을 지우는 작업과 내용만 바꾸는 작업을 구분합니다.

# GXP14에서 세 연결은 독립적입니다. ;로 연결하면 셸은 마지막 종료 코드만 보고하고, &&로 연결하면 나중 검사가 사라집니다.

# GXP15에서 하나의 배치가 세 가지 답을 반환합니다.

{
  "commands": [
    { "command": "nginx -t", "exit_code": 0, "truncated": false, "clipped_bytes": 0,
      "stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n" },
    { "command": "systemctl is-active nginx", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "active\n", "stderr": "" },
    { "command": "tail -5 /var/log/nginx/error.log", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "2026/08/21 09:14:02 [error] upstream timed out\n", "stderr": "" }
  ],
  "job_id": null
}

# GXP17에서 마지막 줄은 다음과 같습니다: 각 명령은 자체 종료 코드를 유지합니다.

# GXP18에서 마지막 줄은 다음과 같습니다: 출력은 128KB로 잘립니다.

# GXP19에서 마지막 줄은 다음과 같습니다: 작업 상태는 원격 디스크에 저장됩니다.

$ scp app.conf operator@router:/etc/app.conf
subsystem request failed on channel 0
scp: Connection closed

ssh_upload({ "profile": "router", "local_path": "./app.conf",
             "remote_path": "/etc/app.conf", "sudo": true,
             "mode": "644", "owner": "root:root", "verify": true })

{
  "files": [{
    "path": "/etc/app.conf",
    "written": true,
    "verified": "verified",
    "reason": null,
    "bytes": 1284
  }]
}

cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old && rm -rf /srv/app

rm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old
# REFUSED before the first command runs

# GXP20에서 마지막 줄은 다음과 같습니다: 복사는 바이트 경계에서 잘립니다.

{
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin",
      "port": 22,
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

# GXP21에서 마지막 줄은 다음과 같습니다: 출력은 128KB로 잘립니다.

ssh_exec({ command: "uptime" })
→ No profile specified. Name one explicitly: production

# GXP22에서 마지막 줄은 다음과 같습니다: 출력은 128KB로 잘립니다.

{
  "secretsFile": "~/.config/ssh-mcp/secrets.json",
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin"
    }
  }
}

shell 명령과 MCP 도구의 차이는 구조화된 출력입니다. 이 서버는 네 가지 도구를 제공합니다: ssh_exec, ssh_file_read, ssh_file_write, ssh_file_list.

SSH MCP 도구

원격 파일 관리

장기 실행 SSH 작업 모니터링

로그 검색 및 상태 확인

파일 전송

참고: 전송 도구는 SFTP를 사용합니다. 레거시 장치가 SFTP를 지원하지 않으면 ssh_exec으로 scp를 사용하세요.

Windows SSH 호환 모드

Windows는 호환 모드를 자동으로 사용합니다. 연결 다중화를 사용할 수 없으면 서버는 명령마다 하나의 연결을 사용하도록 전환합니다. 동일한 도구는 키 기반 SSH에서 계속 사용할 수 있습니다. 별도의 설정이나 Windows 전용 구현은 필요 없습니다.

파괴적 명령 보호 장치는 AI 에이전트용 파괴적 명령 보호에서 다룹니다.

SSH MCP 서버 설정하기

먼저 30초 설치에서 패키지를 실행한 다음 프로필 파일을 만드세요.

SSH 연결 프로필 만들기

원하는 곳에 두면 됩니다. 보통 에이전트 자체 설정 파일 옆에 둡니다. 아래 예시는 ~/.claude/ssh-profiles.json을 사용합니다. 다른 에이전트는 디렉터리를 바꾸세요(~/.codex/, ~/.qwen/, ~/.config/opencode/):

{
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin",
      "port": 22,
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

SSH 프로필을 명시적으로 선택하기

서버가 기본으로 사용하는 프로필은 없습니다. 각 프로필은 서로 다른 머신을 가리키며, 잘못된 머신에 보낸 명령은 이후에 오류 메시지로 되돌릴 수 없습니다. 이름 없이 요청하면 선택할 수 있는 이름 목록이 답으로 옵니다:

ssh_exec({ command: "uptime" })
→ No profile specified. Name one explicitly: production

서버가 SSH에 사용할 수 없는 프로필 — host가 없거나, username이 없거나, mode: "local"인 경우 — 은 불평 없이 건너뛰며, 인식하지 못하는 필드는 그대로 두므로 파일을 다른 도구와 공유할 수 있습니다. 손상된 필드가 있는 프로필은 다른 경우입니다. 필드와 값과 함께 프로필 이름이 표시되고, 정상인 다른 프로필은 계속 작동합니다.

각 프로필은 선택적으로 pathSecurity 블록을 사용하여 파일 도구가 접근할 수 있는 경로를 허용하거나 차단할 수 있습니다 — docs/security.md를 참조하세요.

SSH 비밀번호와 패스프레이즈를 프로필에 넣지 않기

키를 선호하세요. 비밀번호나 암호화된 키의 패스프레이즈를 피할 수 없다면 별도의 시크릿 파일에 보관하고, 절대 프로필 자체에 넣지 마세요:

{
  "secretsFile": "~/.config/ssh-mcp/secrets.json",
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin"
    }
  }
}

시크릿 파일은 프로필 이름을 키로 사용합니다 — secrets.json.example을 참조하세요:

{
  "production": { "password": "..." }
}

시크릿 파일은 사용자 본인만 읽을 수 있어야 합니다(chmod 600). 상대 경로는 프로필 파일을 기준으로 해석됩니다. 시크릿은 argv에 포함되지 않으며 로그에서 마스킹됩니다. 자격 증명 보안을 참조하세요.

Claude Code, Codex 및 기타 MCP 클라이언트 구성하기

사용하는 클라이언트를 선택하고 동일한 프로필 파일을 가리키게 하세요.

Claude Code

명령 하나면 됩니다. -s user는 서버를 모든 프로젝트에서 사용할 수 있게 합니다:

claude mcp add ssh -s user \
  -e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

Codex CLI

codex mcp add ssh \
  --env SSH_PROFILES_FILE="$HOME/.codex/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

opencode

~/.config/opencode/opencode.json에 넣으세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ssh": {
      "type": "local",
      "command": ["npx", "-y", "@hypnosis/ssh-mcp-server"],
      "enabled": true,
      "environment": {
        "SSH_PROFILES_FILE": "~/.config/opencode/ssh-profiles.json"
      }
    }
  }
}

Qwen Code

다른 것들과 마찬가지로 명령 하나면 됩니다:

qwen mcp add ssh \
  -e SSH_PROFILES_FILE="$HOME/.qwen/ssh-profiles.json" \
  npx -y @hypnosis/ssh-mcp-server

기타 MCP 클라이언트

Gemini CLI, Hermes, Cline, 편집기 플러그인 또는 직접 만든 에이전트도 같은 방식으로 작동합니다. 필요한 것은 실행할 명령과 환경 변수 하나뿐입니다.

MCP 클라이언트 다시 시작하기

클라이언트를 다시 시작한 다음 ssh_monitor({ action: "list" })를 실행하여 프로필이 로드되었는지 확인하세요.

SSH MCP 서버 구성

공유 연결은 의도적으로 이 프로세스보다 오래 유지됩니다. 종료 시 연결을 닫으면 같은 머신의 다른 창이 사용 중인 채널이 끊기기 때문입니다.

SSH MCP 서버 제한 사항

• 취소: SSH를 닫으면 원격 명령이 계속 실행 중일 수 있습니다. 제어가 중요하다면 분리된 작업(detached job)을 사용하세요.

• 원자적 쓰기: BSD와 macOS는 파일 시스템 간 이름 변경을 사전에 확인할 수 없습니다.

SSH MCP 서버 로드맵

• macOS SSH 호스트에 대한 전체 테스트 실행

• Windows에서 엔드투엔드 호환성 실행

• 다중 호스트 감사 — 한 번의 호출로 여러 SSH 프로필의 상태 비교

• 기존 ~/.ssh/config에서 프로필 가져오기

• 대용량 파일과 불안정한 연결을 위한 이어서 전송

• 원격 작업 타임라인 — 명령, 전송, 보호 결정을 하나의 감사 추적으로

• 즉시 사용 가능한 SSH 문제 해결 플레이북

• 모델에 도달하는 답변 — 완료: 명령 출력, 일치하는 로그 줄, 머신 이름, 스냅샷 섹션이 텍스트뿐만 아니라 필드에도 전달됩니다

• 더 작은 MCP 도구 스키마 — 완료: 도구 목록이 10% 가벼워졌고, 분리된 작업은 맹목적으로 폴링되는 대신 마지막으로 기록한 줄을 표시합니다

SSH MCP 서버 개발 및 테스트

npm install
npm run build           # tsc
npx tsc --noEmit        # types, plus dead declarations
npm run test:unit       # unit tests
npm run lab:up          # start the two test containers
npm run test:live       # live suite against those containers

실제 테스트 스위트는 실제 컨테이너(BusyBox 하나, coreutils 하나)를 대상으로 실행됩니다. 두 컨테이너는 조용히 의견이 다르고, 모의 객체는 작성자 편에 서기 때문입니다. 구조는 docs/architecture.md를 참조하세요.

SSH MCP 서버가 마음에 드시나요? ⭐

이 도구가 마음에 든다면 GitHub에서 스타를 눌러 주세요 — 더 많은 사람들이 프로젝트를 발견하는 데 도움이 됩니다.

SSH MCP 서버에 기여하기

이슈와 풀 리퀘스트는 github.com/hypnosis/ssh-mcp-server에서 환영합니다.

라이선스

MIT — LICENSE를 참조하세요.