tufantunc/ssh-mcp

SSH MCP Server — AI 에이전트를 위한 제어된 SSH 액세스

개요: AI 어시스턴트(Claude 등)가 SSH를 통해 원격 컴퓨터에서 명령을 실행할 수 있도록 하는 보안 중심의 Model Context Protocol (MCP) server 입니다. LLM과 셸 사이의 가교 역할을 하며, 개인 데이터, 신뢰할 수 없는 입력, 네트워크 액세스라는 '치명적인 3요소'가 한곳에 집중되는 위험을 방지하도록 설계되었습니다.

존재 이유: AI에게 직접적인 셸 액세스 권한을 부여하는 것은 위험합니다. 프롬프트 인젝션으로 인해 악의적인 명령이 실행될 수 있기 때문입니다. 이 서버는 모든 명령을 분류하고, 정책에 따라 검사하며, 위험한 작업에는 인간의 승인을 요구하고, 모든 것을 기록함으로써 다중 제어 계층을 추가합니다.

주요 기능:

• 14개의 도구: 원격 작업을 위한 도구(읽기 전용 명령 ls, cat, 임의 명령, sudo 명령, SFTP 파일 전송(모델 컨텍스트 경유 및 디스크 직접 스트리밍), 대화형/백그라운드 세션, 프로세스 신호 전송).
• 정책 엔진: 명령은 읽기 전용, 안전, 파괴적, 특권 명령으로 분류됩니다. 역할 × 호스트 그룹 행렬에 의해 허용 여부가 결정됩니다. 블랙리스트 패턴(예: terraform destroy)을 정의할 수 있습니다.
• 인간 개입 승인: 파괴적인 명령은 승인이 필요합니다(approvalPolicy = "auto"로 설정하지 않는 한, 프로덕션 환경에서는 권장되지 않음). 승인에는 시간 제한을 둘 수 있습니다.
• 감사 로그: 모든 명령, 승인, 전송 작업이 기록됩니다.
• 보안 강화: 설정 파일 권한 강제 적용(Linux/macOS는 0600/0700 필수, Windows는 ACL 검사). 호스트 키 고정, ProxyJump(배스천) 지원, SSH CA 인증서 지원. root 계정 사용은 권장되지 않음.
• 세션: 대화형 세션은 명령 간에 상태(CWD, 환경 변수)를 유지하며, 백그라운드 세션은 장기 실행 프로세스(예: tail -f)를 폴링할 수 있습니다.
• 스트리밍 파일 전송: 대용량/바이너리 파일은 모델 컨텍스트를 완전히 우회하여 로컬 디스크와 원격 호스트 간에 직접 전송되며, 원자적 쓰기 및 크기/시간 제한을 지원합니다.
• 호스트 측 식별: AI_AGENT=ssh-mcp 환경 변수를 설정하여 운영자가 에이전트 세션을 식별할 수 있도록 합니다(호스트에서 AcceptEnv 필요).

작동 방식: TOML 파일에서 프로필(호스트, 사용자, 인증 방식, 역할, 승인 정책)을 설정합니다. 서버는 SSH(키, 비밀번호, agent, keychain)를 통해 연결됩니다. 에이전트가 도구를 호출하면 서버는 명령을 분류하고, 정책 행렬 및 블랙리스트와 대조하며, 필요시 인간의 승인을 요청한 후 실행합니다. 모든 결정은 기록됩니다.

사용 사례: AI 어시스턴트를 통한 안전한 원격 관리, 감독 하의 자동화된 배포, 모니터링 및 로그 검사, 그리고 LLM에게 무제한 셸 액세스 권한을 주지 않고 서버와 상호작용하게 하려는 모든 시나리오.

중요 주의사항: README는 이 도구가 위험을 줄여주지만 완전히 제거하지는 않는다는 점을 강조합니다. root 계정을 대상으로 사용하거나 프로덕션 프로필에서 auto 승인을 사용하지 마십시오. Linux, macOS, Windows에서 테스트되었으나, Windows에서는 대화형 세션 및 스트리밍 전송에 일부 제한이 있습니다.