ssh‑mcp‑server

무엇인가요

ssh‑mcp‑server는 AI 어시스턴트(또는 Model Context Protocol (MCP)를 사용하는 모든 클라이언트)와 원격 SSH 서버 사이의 브리지 역할을 하는 Node‑JS 유틸리티입니다. 로컬에서 실행되어 SSH 자격 증명을 호스트에 보관하며, MCP 호환 도구(execute‑command, upload, download, read‑file, write‑file, job‑control 등)를 노출하여 AI가 개인 키나 비밀번호를 직접 보지 않고도 서버에 명령 실행이나 파일 이동을 요청할 수 있게 합니다.

AI/ML 워크플로우에서 중요한 이유

• 안전한 원격 실행 – LLM 기반 에이전트는 종종 실제 작업(예: VM 프로비저닝, 로그 가져오기, 코드 배포)을 수행해야 합니다. 이러한 작업을 MCP를 통해 라우팅함으로써 모델이 원시 SSH 자격 증명을 얻지 못하게 하여 공격 표면을 줄입니다.
• 표준화된 인터페이스 – MCP는 여러 AI 코딩 어시스턴트(Claude Code, Cursor 등)에서 사용하는 프로토콜입니다. 이 서버는 해당 사양을 구현하여 MCP를 지원하는 모든 어시스턴트가 원격 호스트를 일급 도구로 취급할 수 있게 합니다.
• 세밀한 보안 제어 – 내장된 명령 화이트리스트/블랙리스트, 출력 크기 제한 및 경로 제한을 통해 운영자는 AI를 안전한 작업(읽기 전용 진단, 로그 수집 등)으로만 제한할 수 있습니다.
• 복잡한 환경 지원 – 비밀번호, 키 기반, 2FA 인증을 지원하며, 베스천 호스트나 SOCKS/HTTP 프록시를 거쳐 연결할 수 있고, 템플릿을 통해 컨테이너 내부에서 명령을 실행할 수도 있습니다.

핵심 기능 (README 설명 기준)

기능	설명
다양한 인증 방식	비밀번호, 개인 키(암호 구문 지원), SSH‑agent 및 키보드 대화형 2FA.
명령 화이트리스트 / 블랙리스트	정규식 기반 허용/거부 목록. 화이트리스트가 우선 적용되어 위험한 파이프라인이나 리다이렉션을 방지합니다.
전송 모드	exec(기본값, SFTP 지원) 및 shell(지속적 셸, 베스천 호스트에 유용하나 파일 전송 불가).
파일 전송	SFTP를 통한 upload / download. 재귀적 디렉토리 지원 및 구성 가능한 허용 경로 목록.
작업 관리	job‑start, job‑status, job‑kill, job‑list. 서버 재시작 후에도 유지되는 장기 실행 백그라운드 작업용.
명령 템플릿	각 명령을 사용자 제공 템플릿(예: sudo bash -c <quotedCommand> 또는 docker exec …)으로 래핑합니다.
멀티 호스트 구성	단일 JSON 구성 파일, --ssh JSON 문자열, 기존 쉼표 구분 구문, 또는 ~/.ssh/config에서 가져오는 쉼표 구분 --host 값.
프록시 지원	--proxy(또는 기존 --socksProxy)를 통한 SOCKS5, HTTP, HTTPS 프록시.
출력 및 리소스 제한	최대 stdout/stderr 크기(기본값 10 MiB), 명령별 타임아웃, 연결 유지 설정 및 선택적 PTY 할당.
제로 설치 실행	npx @fangjunjie/ssh-mcp-server …로 실행 – 전역 설치 불필요.

사용 대상

• AI 코딩 어시스턴트 (Claude Code, Cursor, GitHub Copilot Chat 등)를 사용하여 사용자 인프라에서 실제 명령을 실행해야 하는 경우.
• DevOps 팀이 자동화된 진단, 로그 수집 또는 배포를 위해 LLM 기반 봇을 구축하는 경우.
• 보안 중심 사용자가 AI 모델에 제한된 SSH 작업 세트만 노출하려는 경우.
• 연구원이 클라우드나 온프레미스 서버와 상호 작용하는 자율 에이전트를 실험하는 경우.

시작하기 (README의 빠른 단계)

1. 설치 / 실행 – npx -y @fangjunjie/ssh-mcp-server … (-y 플래그는 npm 설치 프롬프트를 건너뜁니다).
2. MCP 구성 생성 – 예제 JSON 스니펫(예: 간단한 비밀번호 인증)을 MCP 클라이언트의 mcp.json에 복사합니다.
3. 화이트리스트 추가(선택 사항) – 명령을 ls, cat, df와 같은 안전한 명령으로 제한합니다.
4. 도구 호출 – AI 어시스턴트에서 다음과 같은 요청을 보냅니다:

   { "tool": "execute-command", "params": { "cmdString": "ls -al", "connectionName": "dev" } }
   

5. 응답 확인 – 서버는 명령 출력, 종료 코드 및 오류 메타데이터를 반환합니다.

제한 사항 / 미해결 과제 (README 기준)

• 내장된 속도 제한 기능이 없습니다. DoS 공격을 방지하려면 외부 방화벽이나 리버스 프록시가 필요합니다.
• shell 모드는 지속적 셸을 통해 SFTP를 사용할 수 없으므로 파일 전송이 비활성화됩니다.
• 출력 크기 제한은 연결별로 하드코딩되어 있습니다. maxOutputBytes를 0으로 설정하면 보호 기능이 비활성화되지만 권장되지 않습니다.
• 서버는 백그라운드 작업을 위해 원격 호스트의 POSIX sh 환경을 가정합니다.

---

위의 모든 정보는 프로젝트의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.