Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
SSH MCP 도구는 AI 모델이 표준화된 인터페이스(MCP)를 통해 SSH 연결을 관리하고 다양한 서버 작업을 수행할 수 있도록 돕는 개발 도구입니다. 이 도구를 사용하면 AI 비서가 복잡한 명령어 입력 없이도 서버 접속, 파일 조작, 프로세스 관리 등 전문적인 SSH 작업을 자연어 지시만으로 처리할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기ISC License
Node.js
TypeScript
SSH
English Version (README-EN.md)
이것은 MCP (Model Context Protocol) 기반의 SSH 도구로, AI 모델이 표준화된 인터페이스를 통해 SSH 연결에 접근하고 관리할 수 있게 합니다.
간단히 말해, AI 비서가 사용자가 복잡한 명령을 수동으로 입력하거나 터미널로 전환할 필요 없이 서버 연결, 명령어 실행, 파일 관리 등 다양한 SSH 작업을 수행할 수 있도록 합니다.
<details> <summary><b id="功能特点">지원 기능</b> (클릭하여 펼치기)</summary>다음은 SSH MCP 도구의 몇 가지 핵심 특징입니다:
&&와 ;를 포함하는 복합 명령어를 지능적으로 처리합니다.단순한 자연어 지시를 통해 AI가 위에서 언급된 모든 작업을 수동으로 복잡한 SSH 명령어를 작성하거나 터미널에서 실행할 필요 없이 도와줄 수 있습니다.
</details>⚠️ 주의:
당신의 사용자 이름을 Windows 사용자 이름으로 대체하세요.Cursor에서 MCP 설정 파일을 열거나 생성합니다: /Users/당신의 사용자 이름/.cursor/mcp.json
당신의 사용자 이름을 macOS 사용자 이름으로 대체하세요.다음처럼 설정을 추가하거나 수정합니다:
{
"mcpServers": {
"ssh-mcp": {
...
⚠️ 주의:
당신의 사용자 이름을 macOS 사용자 이름으로 대체하세요.Cursor에서 MCP 설정 파일을 열거나 생성합니다: /home/당신의 사용자 이름/.cursor/mcp.json
당신의 사용자 이름을 Linux 사용자 이름으로 대체하세요.다음처럼 설정을 추가하거나 수정합니다:
{
"mcpServers": {
"ssh-mcp": {
...
⚠️ 주의:
당신의 사용자 이름을 Linux 사용자 이름으로 대체하세요.설정을 완료한 후, Cursor 편집기를 재시작하면 MCP 서비스가 자동으로 시작됩니다. 그러면 바로 사용을 시작할 수 있습니다.
요청: 제 서버에 연결하는 새로운 SSH 연결을 만들어 주세요
2. AI 도우미가 다음 정보를 제공하도록 안내할 것입니다:
- 호스트 주소 (IP 또는 도메인)
- 포트 번호 (기본값 22)
- 사용자 이름
- 인증 방식 (비밀번호 또는 키)
- 기타 선택적 설정 (타임아웃 시간, 키 경로 등)
3. 연결 생성 후, 다음 명령을 통해 연결 테스트를 할 수 있습니다:
요청: 방금 만든 SSH 연결을 테스트해 주세요
</details>
## 사용 예시
<details>
<summary><b>기본 명령어 실행</b> (클릭하여 펼치기)</summary>
서버에서 ls -la 명령을 실행해 주세요
AI 도우미는 다음 작업을 수행합니다:
1. 기존 SSH 연결 확인
2. 명령을 실행하고 결과를 반환
3. 가독성을 높이기 위해 출력 형식화
</details>
<details>
<summary><b>tmux 세션 관리</b> (클릭하여 펼치기)</summary>
요청: 새로운 tmux 세션을 만들고 top 명령을 실행해 주세요
AI 도우미는 다음 작업을 수행합니다:
1. 새로운 tmux 세션 생성
2. 세션 내에서 top 명령 실행
3. 후속 사용을 위해 세션 ID 반환
</details>
<details>
<summary><b>파일 조작</b> (클릭하여 펼치기)</summary>
요청: /var/log/syslog 파일의 마지막 100 줄을 확인해 주세요
AI 도우미는 다음 작업을 수행합니다:
1. 파일 권한 확인
2. 적절한 명령을 사용하여 파일 읽기
3. 내용 형식화 및 반환
</details>
## 고급 기능
### 블로킹 감지 (Blocking Detection)
SSH MCP 도구는 지능적인 블로킹 감지 메커니즘을 내장하고 있습니다:
- 대화형 프로그램(예: vim, nano) 자동 감지
- 백그라운드에서 실행되는 블로킹 프로세스 식별
- 대기 타임아웃 시간 설정 지원 (최대 10분)
- 강제 실행 옵션 제공 (force 매개변수 사용)
### 복합 명령어 처리 (Composite Command Handling)
`&&`와 `;`를 포함하는 복합 명령 실행을 지원합니다:
- 여러 명령을 지능적으로 분리 및 실행
- 명령 실행 순서 유지
- 상세한 실행 상태 제공
- 오류 처리 및 롤백(rollback) 지원
### tmux 통합
완벽한 tmux 세션 관리 지원:
- 영속적인(persistent) 세션 생성 및 관리
- 키 입력 시퀀스 전송 지원
- 실시간 세션 출력 캡처
- 지능적인 세션 상태 처리
## 향상된 프롬프트 설정
SSH MCP 도구를 사용하여 원격 서버와 더 잘 협업하기 위해, Cursor에 다음 CursorRules 설정을 추가하는 것이 좋습니다:
<details>
<summary><b>권장되는 CursorRules 설정</b></summary>
사용자 도움이 필요하거나 필요할 수 있는 ssh 작업의 경우, 공유 가능한 터미널 세션인 tmux를 생성하고, 사용자에게 어떤 명령을 통해 tmux에 연결하여 협업할 수 있는지 직접 <b>알려주세요</b>(mcp 내에서 사용자에게 알려주는 것이 아니라, 출력으로 보여줘야 합니다). 그런 다음 작업을 시작하세요.
<b>반드시 tmux 내부에서 작업을 수행해야 합니다. tmux send-keys 관련 명령을 사용할 수 있으며, mcp는 자동으로 현재 실행 중인 명령어와 직전에 실행된 명령어의 결과를 반환합니다.</b>
...
</details>
이 설정을 추가하면 AI 어시스턴트가 SSH 작업을 더 지능적으로 처리할 수 있게 되며, 특히 사용자 협업이 필요한 시나리오에서 공유 tmux 세션을 생성하여 원격 조작을 더욱 효율적이고 투명하게 만들 수 있습니다.
## 작동 원리
<details>
<summary>기술 구현 상세 (클릭하여 펼치기)</summary>
본 도구는 **MCP (Model Context Protocol)** 표준을 기반으로 구현되었으며, AI 모델과 SSH 서비스 간의 다리 역할을 합니다. 이는 **node-ssh**를 기본 SSH 클라이언트로 사용하고, **Zod**를 통해 요청 검증 및 타입 체크를 수행합니다.
주요 기술 구성 요소는 다음과 같습니다:
- **SSH 클라이언트**: SSH 연결을 설정하고 유지하며, 비밀번호 및 키 인증을 지원합니다.
- **tmux 관리자**: tmux 세션의 생성, 관리 및 상호 작용을 처리합니다.
- **명령 실행 시스템**: 단일 명령어 및 복합 명령어 실행을 지원하며, 블로킹 감지 기능을 제공합니다.
- **프로세스 모니터링**: 프로세스 상태를 실시간으로 감지하여 세션이 멈추는 것을 방지합니다.
- **파일 전송**: 업로드 및 다운로드 기능을 지원하며, 다양한 파일 형식을 처리합니다.
모든 SSH 작업은 표준화된 MCP 도구로 캡슐화되어 구조화된 매개변수를 받고 형식화된 결과를 반환합니다. 모든 원격 명령어는 처리되어 인간이 읽을 수 있는 형식으로 보장되며, AI 모델이 명령어 실행 결과를 쉽게 이해할 수 있도록 합니다.
</details>
## 기여 가이드
Issue와 Pull Request를 제출해 주시면 환영합니다! 제출하기 전에 다음 사항을 확인해 주세요:
1. 기존 Issue 및 PR 검토
2. 프로젝트의 코드 스타일 준수
3. 적절한 테스트 케이스 추가
4. 관련 문서 업데이트
## 라이선스
본 프로젝트는 ISC 라이선스를 채택했습니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
---
이 프로젝트가 도움이 되었다면, Star ⭐️ (｡♥‿♥｡) 를 부탁드립니다.
## Docker로 실행하기 (권장)
이 도구를 Docker 컨테이너에서 실행할 수도 있습니다. 이는 로컬 환경과 잠재적인 충돌을 피할 수 있어 권장되는 사용 방식입니다.
1. **Docker 이미지 빌드:**
```bash
docker build -t mcp-ssh .
연결 구성 및 자격 증명이 컨테이너 재시작 후에도 손실되지 않도록, Docker 볼륨(Volume) 사용을 강력히 권장합니다.
# (최초 실행 전) 데이터를 저장할 볼륨 생성
docker volume create mcp-ssh-data
...
Windows에서는 ~/.ssh 대신 %USERPROFILE%\.ssh를 사용하세요:
docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v %USERPROFILE%\.ssh:/root/.ssh mcp-ssh