🔐 ssh-mcp-server

Name: ssh-mcp-server
Author: classfang

NPM Version GitHub forks GitHub Repo stars GitHub Issues or Pull Requests

MCP(Model Context Protocol) 프로토콜을 통해 원격 SSH 명령을 실행할 수 있는 SSH 기반 MCP 서버입니다.

English Document | 中文文档

📝 프로젝트 개요

ssh-mcp-server는 AI 어시스턴트 및 MCP 프로토콜을 지원하는 기타 애플리케이션이 표준화된 인터페이스를 통해 원격 SSH 명령을 실행할 수 있도록 하는 브리지 도구입니다. 이를 통해 AI 어시스턴트는 SSH 자격 증명을 AI 모델에 직접 노출하지 않고도 안전하게 원격 서버를 운영하고, 명령을 실행하며, 결과를 검색할 수 있습니다.

위챗 그룹에 참여하세요:

✨ 주요 기능

🔒 보안 연결: 비밀번호 인증 및 개인 키 인증(암호 구문 지원 포함)을 포함한 다양한 보안 SSH 연결 방식 지원
🛡️ 명령 보안 제어: 유연한 블랙리스트 및 화이트리스트 메커니즘을 통해 허용된 명령 범위를 정밀하게 제어하여 위험한 작업 방지
🔄 표준화된 인터페이스: MCP 프로토콜 사양을 준수하여 해당 프로토콜을 지원하는 AI 어시스턴트와 원활하게 통합
📂 파일 전송: 양방향 파일 전송 지원, 로컬 파일을 서버로 업로드하거나 서버에서 파일 다운로드 가능
🔑 자격 증명 격리: SSH 자격 증명은 완전히 로컬에서 관리되며 AI 모델에 노출되지 않아 보안 강화
🚀 즉시 사용 가능: 전역 설치 없이 NPX를 사용하여 직접 실행할 수 있어 배포가 간편하고 빠름

📦 오픈 소스 저장소

GitHub: https://github.com/classfang/ssh-mcp-server

NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server

🛠️ 도구 목록

도구	이름	설명
execute-command	명령 실행 도구	원격 서버에서 SSH 명령을 실행하고 결과 획득
upload	파일 업로드 도구	로컬 파일을 원격 서버의 지정된 위치로 업로드
download	파일 다운로드 도구	원격 서버에서 로컬 지정 위치로 파일 다운로드
list-servers	서버 목록 도구	사용 가능한 모든 SSH 서버 구성 나열

📚 사용법

🔧 MCP 구성 예시

⚠️ 중요: MCP 구성 파일에서 각 명령줄 인수와 그 값은 args 배열의 별도 요소여야 합니다. 공백으로 결합하지 마십시오. 예를 들어 "--host 192.168.1.1" 대신 "--host", "192.168.1.1"을 사용하십시오.

⚙️ 명령줄 옵션

Options:
  --config-file       JSON configuration file path (recommended for multiple servers)
  --ssh-config-file   SSH config file path (default: ~/.ssh/config)
  --ssh               SSH connection configuration (can be JSON string or legacy format)
  -h, --host          SSH server host address or alias from SSH config
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  --allowed-local-paths Additional allowed local paths for upload/download, comma-separated
  --pty               Allocate pseudo-tty for command execution (default: true)
  --pre-connect       Pre-connect to all configured SSH servers on startup

🔑 비밀번호 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

🔐 개인 키 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

🔏 암호 구문이 포함된 개인 키 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

📋 ~/.ssh/config 사용

~/.ssh/config 파일에 정의된 호스트 별칭을 사용할 수 있습니다. 서버는 SSH 구성에서 연결 매개변수를 자동으로 읽습니다:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver"
      ]
    }
  }
}

~/.ssh/config에 다음이 포함되어 있다고 가정합니다:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

사용자 지정 SSH 구성 파일 경로를 지정할 수도 있습니다:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

참고: 명령줄 매개변수가 SSH 구성 값보다 우선합니다. 예를 들어 --port 2222를 지정하면 SSH 구성의 포트보다 우선 적용됩니다.

🌐 SOCKS 프록시 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}

📝 명령 화이트리스트 및 블랙리스트 사용

--whitelist 및 --blacklist 매개변수를 사용하여 실행 가능한 명령 범위를 제한합니다. 여러 패턴은 쉼표로 구분합니다. 각 패턴은 명령을 일치시키는 데 사용되는 정규식입니다.

예시: 명령 화이트리스트 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

예시: 명령 블랙리스트 사용

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}

참고: 화이트리스트와 블랙리스트가 모두 지정된 경우, 시스템은 먼저 명령이 화이트리스트에 있는지 확인한 다음 블랙리스트에 있는지 확인합니다. 명령이 실행되려면 두 검사를 모두 통과해야 합니다.

🧩 다중 SSH 연결 예시

다중 SSH 연결을 구성하는 세 가지 방법이 있습니다:

📄 방법 1: 구성 파일 사용 (권장)

JSON 구성 파일(예: ssh-config.json)을 생성합니다:

배열 형식:

[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
]

객체 형식:

{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
}

그런 다음 --config-file 매개변수를 사용합니다:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 방법 2: --ssh 매개변수와 함께 JSON 형식 사용

JSON 형식의 구성 문자열을 직접 전달할 수 있습니다:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
      ]
    }
  }
}

📝 방법 3: 레거시 쉼표 구분 형식 (하위 호환성)

비밀번호에 특수 문자가 없는 간단한 경우에는 레거시 형식을 계속 사용할 수 있습니다:

npx @fangjunjie/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"

⚠️ 참고: 레거시 형식은 =, ,, {, }와 같은 특수 문자가 포함된 비밀번호에서 문제가 발생할 수 있습니다. 특수 문자가 포함된 비밀번호는 방법 1 또는 방법 2를 사용하십시오.

MCP 도구 호출 시 connectionName 매개변수를 통해 연결 이름을 지정합니다. 생략하면 기본 연결이 사용됩니다.

예시 ('prod' 연결에서 명령 실행):

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

예시 (타임아웃 옵션으로 명령 실행):

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

⏱️ 명령 실행 타임아웃

execute-command 도구는 명령이 무기한 중단되는 것을 방지하기 위해 타임아웃 옵션을 지원합니다:

timeout: 명령 실행 타임아웃(밀리초 단위, 선택 사항, 기본값은 30000ms)
오류 응답에는 에이전트 측에서 더 쉽게 처리할 수 있도록 안정적인 code, message, retriable 필드가 포함됩니다.

이는 ping, tail -f 또는 실행을 차단할 수 있는 기타 장기 실행 프로세스와 같은 명령에 특히 유용합니다.

🗂️ 모든 SSH 서버 나열

MCP 도구 list-servers를 사용하여 사용 가능한 모든 SSH 서버 구성을 가져올 수 있습니다:

호출 예시:

{
  "tool": "list-servers",
  "params": {}
}

응답 예시:

[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

🛡️ 보안 고려 사항

이 서버는 원격 서버에서 명령을 실행하고 파일을 전송할 수 있는 강력한 기능을 제공합니다. 안전하게 사용하려면 다음 사항을 고려하십시오:

명령 화이트리스트: 실행 가능한 명령 집합을 제한하기 위해 --whitelist 옵션을 사용하는 것을 강력히 권장합니다. 화이트리스트가 없으면 원격 서버에서 모든 명령을 실행할 수 있으며, 이는 심각한 보안 위험이 될 수 있습니다.
개인 키 보안: 서버는 SSH 개인 키를 메모리로 읽습니다. ssh-mcp-server를 실행하는 머신이 안전한지 확인하십시오. 신뢰할 수 없는 네트워크에 서버를 노출하지 마십시오.
서비스 거부(DoS): 서버에는 기본 제공 속도 제한이 없습니다. 공격자가 연결 요청이나 대용량 파일 전송으로 서버를 범람시켜 DoS 공격을 시도할 수 있습니다. 속도 제한 기능이 있는 방화벽이나 리버스 프록시 뒤에서 서버를 실행하는 것이 좋습니다.
경로 탐색: 서버에는 로컬 파일 시스템에 대한 경로 탐색 공격을 방지하는 기본 보호 기능이 있습니다. 그러나 upload 및 download 명령에 사용되는 경로에 주의하는 것이 여전히 중요합니다.
로컬 전송 범위: 기본적으로 로컬 파일 전송은 현재 작업 디렉토리로 제한됩니다. 명시적으로 신뢰할 수 있는 디렉토리에 대해서만 구성에서 --allowed-local-paths 또는 allowedLocalPaths를 사용하십시오.

ssh-mcp-server