ssh-mcp v4.0

Linux 호스트 및 네트워크 장치에서 지속적인 SSH 작업을 위한 MCP 서버입니다.

기능

• 지속적인 SSH 연결 및 자동 재연결 지원

• 안전한 자격 증명 저장 - Windows 자격 증명 관리자 활용

• 네트워크 장치 지원: Cisco IOS/IOS-XE/XR, MikroTik, FortiGate, Juniper

• 구성 관리: 네트워크 장치의 백업, 복원, 비교

• SFTP: 원격 파일 업로드, 다운로드, 목록 확인

• SSH 터널: 지속적인 포트 포워딩

• 속도 제한: 장치 과부하 방지 (명령 간 100ms 최소 간격)

• 스마트 연결: ssh_connect(alias='vps')로 저장된 자격 증명을 자동으로 불러와 연결

Related MCP server: SSH MCP Server

빠른 시작

1. 서버 저장 (최초 1회)

ssh_save_server(
    alias='vps',
    host='192.168.10.1',
    username='sassogba',
    password='your-password',
    auto_connect=True  # Auto-connect on startup
)

2. 연결 (간편 모드)

ssh_connect(alias='vps')  # Loads credentials from servers.json

3. 명령 실행

ssh_exec(alias='vps', command='df -h')
ssh_exec_sudo(alias='vps', command='systemctl restart nginx', sudo_password='...')

v4.0 새로운 기능

스마트 연결 모드

• ssh_connect가 별칭만으로 자격 증명을 자동으로 불러와 연결

• 호스트, 사용자 이름, 비밀번호를 매번 입력할 필요 없음

• Claude Code 통합 문제 해결

주요 수정 사항

• 시간 초과 처리: 불완전한 버퍼를 조용히 반환하는 대신 TimeoutError를 발생시킴

• 속도 제한: 장치 과부하 방지를 위해 명령 간 100ms 최소 간격 적용

• 매직 넘버 제거: 셸 차원을 위한 명명된 상수 사용

문서

• 새 CLAUDE_CODE_USAGE.md - 전체 사용 예시 포함

• 새 CLAUDE_CODE_SETUP.md - 구성 방법 안내

• 새 CHANGELOG.md - 전체 버전 이력 포함

보안 모델

servers.json에는 민감하지 않은 메타데이터만 저장됩니다. 비밀번호는 Windows 자격 증명 관리자에 다음 형식으로 저장됩니다:

• ssh-mcp:<별칭>:password

• ssh-mcp:<별칭>:key_passphrase

호스트 키 정책

• strict: 기본값, 알 수 없는 호스트 키 거부 (프로덕션 환경)

• auto_add: 알 수 없는 호스트 키 자동 수락 (랩 환경 전용)

네트워크 장치

지원 장치 유형:

• cisco - Cisco IOS/IOS-XE

• cisco_xr - Cisco IOS-XR

• mikrotik - MikroTik RouterOS

• fortigate - FortiGate FortiOS

• juniper - Juniper JunOS

• generic - Linux/Unix (기본값)

예시: Cisco 백업

# Save once
ssh_save_server(
    alias='cisco-core',
    host='10.0.0.1',
    username='admin',
    password='...',
    device_type='cisco',
    auto_connect=True
)

# Connect
ssh_connect(alias='cisco-core')

# Backup config
ssh_backup_config(alias='cisco-core', device_type='cisco')
# Saved to: backups/cisco-core/cisco-core_2026-05-31_14-30-00.txt

# Execute commands
ssh_exec_network(
    alias='cisco-core',
    commands=['show version', 'show ip interface brief'],
    device_type='cisco'
)

# Push config
ssh_push_config(
    alias='cisco-core',
    config='''
interface GigabitEthernet0/1
 description Uplink to Core
 ip address 10.0.1.1 255.255.255.0
 no shutdown
''',
    device_type='cisco',
    save_config=True
)

Claude Code 사용법

자세한 예시는 CLAUDE_CODE_USAGE.md를 참조하세요.

요약:

1. Save: ssh_save_server(alias='vps', host='192.168.10.1', username='sassogba', password='...')
2. Connect: ssh_connect(alias='vps')
3. Execute: ssh_exec(alias='vps', command='df -h')

사용 가능한 18가지 도구

연결 관리

• ssh_connect - 지속적인 SSH 연결 수립 (스마트 모드: 별칭만 입력)

• ssh_disconnect - 연결 및 터널 종료

• ssh_list - 활성 연결 목록 및 상태 확인

지속적인 구성

• ssh_save_server - 서버를 servers.json에 저장 (비밀번호는 자격 증명 관리자에)

• ssh_remove_server - 저장된 서버 삭제

• ssh_list_servers - 저장된 모든 서버 목록 확인

Linux/Unix 명령 실행

• ssh_exec - 셸 명령 실행

• ssh_exec_sudo - sudo로 명령 실행 (비밀번호 자동 입력)

네트워크 장치 명령 실행

• ssh_exec_network - 네트워크 장치에서 명령 실행 (페이지네이션, 프롬프트 처리)

• ssh_push_config - 구성 블록 배포

• ssh_backup_config - 실행 중인 구성을 로컬 파일로 백업

• ssh_restore_config - 백업 파일에서 구성 복원

• ssh_diff_config - 구성 비교 (git 스타일 diff)

SFTP

• ssh_upload - 원격 서버로 파일 업로드

• ssh_download - 원격 서버에서 파일 다운로드

• ssh_list_remote - 원격 디렉토리 내용 확인

터널

• ssh_tunnel - 지속적인 SSH 터널 생성 (포트 포워딩)

• ssh_close_tunnel - 별칭으로 터널 종료

아키텍처

• SSHPool: 자동 재연결 기능이 있는 스레드 안전 연결 풀

• SSHConnection: 스레드 안전성을 위한 RLock이 적용된 연결별 상태 관리

• ThreadPoolExecutor: Paramiko(동기식)용 비동기/대기 래퍼

• 속도 제한기: 장치 과부하 방지를 위한 명령 간 100ms 최소 간격

• 시간 초과 처리: 다중 레벨(명령별, 전체, 절대) 시간 초과 및 적절한 오류 전파

요구 사항

paramiko>=3.0.0
mcp>=1.0.0
pywin32>=306

설치:

pip install -r requirements.txt

테스트 실행

python -m pytest tests -v

문서

• CLAUDE_CODE_USAGE.md - Claude Code 사용 예시

• CLAUDE_CODE_SETUP.md - 구성 방법 안내

• CHANGELOG.md - 버전 이력 및 마이그레이션 안내

라이선스

MIT