MCP SSH 관리자 - Model Context Protocol을 통한 SSH 원격 서버 관리 🚀

Claude Code 및 OpenAI Codex가 여러 SSH 연결을 관리할 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트에서 직접 서버의 명령 실행, 파일 전송, 데이터베이스 관리, 백업 생성, 상태 모니터링, DevOps 작업 자동화를 수행하세요.

🎉 v3.2.2 새로운 기능

전역 설치 수정 및 CLI 바이너리 (출시일: 2026년 4월 7일)

• 🔧 전역 설치 수정: .env 경로 확인 시 하드코딩된 __dirname 대신 폴백 체인을 사용하여 npm install -g와 올바르게 작동하도록 수정됨 (#16, #19)

  • 폴백 체인: ~/.ssh-manager/.env → cwd/.env → ~/.env → 프로젝트 .env

  • 첫 ssh-manager server add 실행 시 ~/.ssh-manager/.env 자동 생성

• 📦 ssh-manager CLI 바이너리 등록: npm install -g 실행 시 mcp-ssh-manager 및 ssh-manager 명령이 모두 생성됨 (#18)

• ⚡ 경쟁 상태(Race condition) 수정: MCP 서버가 요청을 수락하기 전에 서버 설정이 완전히 로드되도록 수정됨

Related MCP server: MCP Server for FTP Access

이전 릴리스

v3.2.0 - ProxyJump / Bastion 호스트 지원 (2026년 3월 18일)

• 🔀 ProxyJump 지원: 간단한 PROXYJUMP 설정 필드를 사용하여 배스천/점프 호스트 뒤에 있는 서버에 연결 (#15)

  • 재귀적 연결을 통해 여러 점프(A → B → C) 체인 구성 가능

  • 순환 참조 감지를 통해 무한 루프 방지

  • 모든 도구가 점프 호스트를 통해 투명하게 작동

• 📦 npx 지원 수정: npx mcp-ssh-manager가 올바르게 작동하도록 수정됨 (#14)

v3.1.5 - SSH 에이전트 및 암호문(Passphrase) 지원 (2026년 3월 5일)

• 🔑 SSH 에이전트 지원: SSH_AUTH_SOCK 사용 가능 시 ssh-agent를 자동으로 사용 — 암호문으로 보호된 키도 투명하게 작동

• 🔐 암호문 설정: .env 및 TOML 형식 모두에 새로운 passphrase 필드 추가

초기 기여를 해주신 @snjax 님께 감사드립니다 (#12).

v3.1.4 - Windows SSH 호스트 지원 (2026년 2월 22일)

• 🪟 Windows SSH 호스트 수정: OpenSSH를 실행하는 Windows 호스트에서 명령이 실패하지 않도록 수정 (#10)

• 서버별 새로운 platform 설정 필드 추가 (SSH_SERVER_FOO_PLATFORM=windows 또는 TOML에서 platform = "windows")

• platform=windows인 경우, Linux timeout/sh -c 명령 래퍼를 건너뛰고 SSH 라이브러리의 기본 타임아웃을 사용

• 모든 도구(ssh_execute, ssh_tail, ssh_monitor, ssh_deploy, ssh_execute_sudo, ssh_group_execute)가 플랫폼을 인식함

v3.1.2 - Windows 호환성 수정 (2026년 2월 9일)

• 🪟 Windows 지원: process.env.HOME이 정의되지 않은 Windows 환경에서 발생하는 충돌 수정 (#8)

• 이제 플랫폼 간 호환성(Linux, macOS, Windows)을 위해 os.homedir()을 사용

v3.1.0 - 도구 활성화 시스템 (2025년 11월 15일)

🎯 컨텍스트 사용 최적화

• 92% 컨텍스트 감소: 필요한 도구만 활성화 (최소 모드: 5개 도구 vs 전체 37개)

• 도구 관리 CLI: ssh-manager tools list/configure/enable/disable

• 6개 도구 그룹: Core, Sessions, Monitoring, Backup, Database, Advanced

• 자동 승인 내보내기: Claude Code 자동 승인 설정 생성

v3.0.0 - 엔터프라이즈 DevOps 플랫폼 (2025년 10월 1일)

이 릴리스에서는 SSH 관리자를 포괄적인 DevOps 자동화 플랫폼으로 변환하는 12개의 새로운 MCP 도구가 추가되었습니다:

💾 백업 및 복원 시스템 (4개 도구)

• MySQL, PostgreSQL, MongoDB 및 파일 시스템을 위한 자동 백업

• cron 통합 및 보존 정책을 포함한 스마트 스케줄링

• 데이터베이스 간 지원을 포함한 원클릭 복원

• 감사 및 규정 준수를 위한 메타데이터 추적

🏥 상태 및 모니터링 (4개 도구)

• CPU, RAM, 디스크 및 네트워크 메트릭을 포함한 실시간 상태 확인

• nginx, mysql, docker 및 사용자 지정 서비스를 위한 서비스 모니터링

• CPU/RAM 정렬 및 종료 기능을 갖춘 프로세스 관리

• 설정 가능한 알림을 포함한 경고 임계값

🗄️ 데이터베이스 관리 (4개 도구)

• 압축 및 선택적 내보내기를 포함한 안전한 데이터베이스 덤프

• 자동 압축 해제를 포함한 데이터베이스 가져오기

• 데이터베이스, 테이블 및 컬렉션을 나열하는 스키마 탐색

• SQL 인젝션 방지(SELECT 전용)를 포함한 보안 쿼리

📊 총계: 37개 MCP 도구 | 🔧 ~4,100줄의 코드 추가 | ✅ 프로덕션 준비 완료

전체 변경 로그 읽기 →

📑 목차

• 기능

• 도구 관리

• 전제 조건

• 빠른 시작 - Claude Code

• 빠른 시작 - OpenAI Codex

• 사용 가능한 MCP 도구

• 설정

• 사용 예시

• 보안

• 문제 해결

• 알려진 제한 사항

• 기여

• 라이선스

🌟 기능

핵심 기능

• 🔗 다중 SSH 연결 - 단일 인터페이스에서 무제한 SSH 서버 관리

• 🔐 보안 인증 - 비밀번호, SSH 키 및 ssh-agent 인증 지원 (암호문으로 보호된 키 포함)

• 🔀 ProxyJump / 배스천 호스트 - 체인형 다중 홉 지원을 통해 점프 호스트 뒤의 서버에 연결

• 📁 파일 작업 - 로컬 및 원격 시스템 간 파일 업로드 및 다운로드

• ⚡ 명령 실행 - 작업 디렉터리 지원을 통해 원격 서버에서 명령 실행

• 📂 기본 디렉터리 - 편의를 위해 서버별 기본 작업 디렉터리 설정

• 🎯 간편한 설정 - 가이드 설정 도구를 포함한 간단한 .env 파일 설정

엔터프라이즈 DevOps 기능 (v3.0) 🎉

• 💾 백업 및 복원 - MySQL, PostgreSQL, MongoDB 및 파일에 대한 자동 백업

• 🏥 상태 모니터링 - 실시간 서버 상태 확인 (CPU, RAM, 디스크, 서비스)

• 🗄️ 데이터베이스 관리 - SQL 인젝션 방지를 포함한 안전한 데이터베이스 작업

• 📊 프로세스 관리 - 서버 프로세스 모니터링 및 제어

• ⚠️ 스마트 경고 - 설정 가능한 상태 임계값 및 알림

v2.0 기능

• 🚀 Bash CLI - 서버 관리를 위한 초고속 순수 Bash CLI

• 📊 고급 로깅 - 레벨 및 기록을 포함한 포괄적인 로깅 시스템

• 🔄 Rsync 통합 - rsync 지원을 통한 양방향 파일 동기화

• 💻 지속적 세션 - 여러 명령에 걸쳐 셸 컨텍스트 유지

• 👥 서버 그룹 - 여러 서버에서 동시에 명령 실행

• 🔧 SSH 터널 - 로컬/원격 포트 포워딩 및 SOCKS 프록시 지원

• 📈 시스템 모니터링 - CPU, 메모리, 디스크 및 네트워크 실시간 모니터링

• 🏷️ 서버 별칭 - 전체 서버 이름 대신 짧은 별칭 사용

• 🚀 스마트 배포 - 권한 처리를 포함한 자동 파일 배포

• 🔑 Sudo 지원 - sudo 권한으로 안전하게 명령 실행

• 📝 OpenAI Codex 지원 - TOML 설정을 통해 OpenAI Codex와 호환

⚙️ 도구 관리 및 컨텍스트 최적화

v3.1 신규: 도구 활성화 관리를 통해 Claude Code 컨텍스트 사용량을 92% 줄이세요!

MCP SSH 관리자는 6개 그룹으로 구성된 37개의 도구를 포함합니다. 기본적으로 모든 도구가 활성화되어 있지만, 특정 워크플로우에 맞게 최적화할 수 있습니다:

빠른 설정

# Interactive configuration wizard
ssh-manager tools configure

# View current configuration
ssh-manager tools list

# Enable/disable specific groups
ssh-manager tools enable monitoring
ssh-manager tools disable backup

설정 모드

도구 그룹

• Core (5개 도구) - 항상 활성화: list, execute, upload, download, sync

• Sessions (4개 도구) - 지속적 SSH 세션

• Monitoring (6개 도구) - 상태 확인, 서비스 상태, 프로세스 관리

• Backup (4개 도구) - 데이터베이스 및 파일 백업

• Database (4개 도구) - MySQL, PostgreSQL, MongoDB 작업

• Advanced (14개 도구) - 배포, sudo, 터널, 그룹, 별칭 등

이점

• 최소 모드에서 92% 컨텍스트 감소 (~40k 토큰 절약)

• Claude Code에서 승인 프롬프트 감소

• 더 빠른 로딩 및 더 깔끔한 인터페이스

• Claude Code를 위한 자동 승인 설정 내보내기

📖 전체 도구 관리 가이드 →

📋 전제 조건

• Node.js (v18 이상)

• npm (Node.js와 함께 설치됨)

• 플랫폼: Linux, macOS, Windows

• Claude Code용: Claude Code CLI 설치됨

• OpenAI Codex용: Codex CLI 설정됨

• Bash 4.0+ (CLI 관리 도구용)

• rsync (파일 동기화용)

• sshpass (선택 사항, 비밀번호 인증을 사용하는 rsync용)

  • macOS: brew install hudochenkov/sshpass/sshpass

  • Linux: apt-get install sshpass

🚀 빠른 시작 - Claude Code

1. MCP SSH 관리자 설치

옵션 A: npm에서 설치 (권장)

# Install globally from npm
npm install -g mcp-ssh-manager

# Or install locally
npx mcp-ssh-manager

옵션 B: 소스에서 설치

# Clone and install
git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager
npm install

# Install the Bash CLI
cd cli && ./install.sh

# Configure your first server
ssh-manager server add

2. Claude Code에 설치

# For personal use (current user only)
claude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js

# For team sharing (creates .mcp.json in project)
claude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js

# For all your projects
claude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js

3. 자동 승인 설정 (선택 사항이지만 권장)

모든 SSH 명령마다 승인 프롬프트가 뜨는 것을 방지하려면 자동 승인 설정을 추가하세요:

~/.config/claude-code/claude_code_config.json 편집:

{
  "mcpServers": {
    "ssh-manager": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-manager/src/index.js"],
      "autoApprove": [
        "mcp__ssh-manager__ssh_execute",
        "mcp__ssh-manager__ssh_list_servers",
        "mcp__ssh-manager__ssh_upload",
        "mcp__ssh-manager__ssh_download",
        "mcp__ssh-manager__ssh_sync",
        "mcp__ssh-manager__ssh_alias"
      ]
    }
  }
}

중요: 이 변경 후 Claude Code를 다시 시작하세요.

모든 SSH 도구의 전체 자동 승인에 대해서는 examples/claude-code-config.example.json의 전체 목록을 참조하세요.

4. 사용 시작!

이제 Claude Code에서 다음을 수행할 수 있습니다:

"List all my SSH servers"
"Execute 'ls -la' on production server"  # Uses default directory if set
"Run 'docker ps' on staging"
"Upload config.json to production:/etc/app/config.json"
"Download logs from staging:/var/log/app.log"

기본 디렉터리 사용: 프로덕션 환경의 기본 디렉터리를 /var/www/html로 설정하면 다음 명령은 동일합니다:

• "Run 'ls' on production" → /var/www/html에서 실행

• "Run 'ls' on production in /tmp" → /tmp에서 실행 (기본값 재정의)

🚀 빠른 시작 - OpenAI Codex

1. MCP SSH 관리자 설치

Claude Code와 동일하게 설치한 후 Codex용으로 설정하세요:

# Set up Codex integration
ssh-manager codex setup

# Migrate existing servers to TOML format (if you have .env servers)
ssh-manager codex migrate

# Test the integration
ssh-manager codex test

2. 수동 설정 (선택 사항)

수동 설정을 선호하는 경우 ~/.codex/config.toml