SSH 원격 MCP 서버

MCP(Model Context Protocol)를 통해 MCP 호환 클라이언트에 대한 SSH 원격 액세스를 제공합니다.

빠른 시작

MCP 서버를 실행할 동일한 OS에서 생성된 가상 환경을 사용하십시오. Windows와 WSL/Linux 간에 venv를 공유하지 마십시오.

Windows

1. 설치:

   .\install.ps1

2. Claude Desktop, Claude Code 또는 Codex에 MCP 추가:

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "C:\\Users\\Intel\\Desktop\\adremote-mcp\\.venv-win\\Scripts\\python.exe",
         "args": [
           "C:\\Users\\Intel\\Desktop\\adremote-mcp\\ssh_mcp_server.py"
         ]
       }
     }
   }

   paramiko와 mcp가 설치된 Windows Python이 이미 있는 경우, .venv-win 대신 해당 인터프리터를 직접 사용할 수 있습니다.

WSL/Linux

1. 설치:

   ./install.sh

2. Claude Desktop, Claude Code 또는 Codex에 MCP 추가:

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "/home/user/adremote-mcp/.venv-linux/bin/python",
         "args": [
           "/home/user/adremote-mcp/ssh_mcp_server.py"
         ]
       }
     }
   }

   Windows 드라이브에서 WSL을 통해 리포지토리에 액세스하는 경우, WSL 경로를 사용하십시오:

   {
     "mcpServers": {
       "ssh-remote": {
         "command": "/mnt/c/Users/Intel/Desktop/adremote-mcp/.venv-linux/bin/python",
         "args": [
           "/mnt/c/Users/Intel/Desktop/adremote-mcp/ssh_mcp_server.py"
         ]
       }
     }
   }

휴대용 런처

일치하는 OS용으로 포함된 런처를 MCP 클라이언트에 지정할 수도 있습니다:

• Windows: C:\Users\Intel\Desktop\adremote-mcp\run-ssh-mcp.cmd

• WSL/Linux: /path/to/adremote-mcp/run-ssh-mcp.sh

런처는 OS별 venv를 우선적으로 사용하며, 그 다음 python3 또는 python으로 대체됩니다. Windows에서는 SSH_MCP_PYTHON을 설정하여 특정 Python 인터프리터를 강제로 지정할 수 있습니다.

WSL/Linux 클라이언트의 경우, 스크립트가 실행 가능으로 표시되지 않은 경우 args: ["/path/to/adremote-mcp/run-ssh-mcp.sh"]와 함께 command: "/bin/sh"를 사용하십시오.

직접 실행

종속성을 설치한 후 서버를 직접 실행할 수 있습니다:

Windows:

.\.venv-win\Scripts\python.exe .\ssh_mcp_server.py

WSL/Linux:

./.venv-linux/bin/python ssh_mcp_server.py

자동 설정

이 리포지토리를 다운로드하고 Claude 또는 Codex를 실행한 다음, 현재 OS의 전역 MCP 서버로 이 폴더를 추가하도록 요청하십시오. 그 후에는 채팅에서 직접 사용할 수 있습니다.

문제 해결

Windows에서 다음과 같이 보고하는 경우:

No Python at '"/usr/bin\python.exe'

MCP가 WSL/Linux에서 생성된 venv를 가리키고 있는 것입니다. .\install.ps1로 Windows venv를 생성하고 MCP 명령을 .venv-win\Scripts\python.exe로 업데이트하십시오.

Related MCP server: MCP SSH Server

기능

• Windows 및 Linux의 MCP 호환 클라이언트와 작동

• SSH를 통해 원격 서버에 연결

• 기본 SSH 점프 호스트 / 배스천 지원

• 원격으로 명령 실행

• SFTP를 통한 파일 업로드/다운로드

• 다중 연결 관리

• 상태 모니터링

사용 예시

비밀번호로 연결:

Connect to 192.168.1.100 with username ubuntu and password mypass

또는 더 짧은 형식:

ssh 192.168.1.100:22 ubuntu mypass

MCP는 먼저 사용자 이름과 비밀번호로 SSH 연결을 테스트합니다. 로그인이 성공하면 SSH 키를 생성하거나 설치하고, 키 기반 자격 증명을 로컬에 저장하며 비밀번호는 저장하지 않습니다. 비밀번호는 처음 한 번만 사용됩니다.

일회성 세션에 비밀번호로 연결:

ssh 192.168.1.100:22 ubuntu mypass, save_credentials false

이것은 라이브 연결만 유지합니다. 재사용 가능한 자격 증명은 저장되지 않으며 자동 키 부트스트랩도 시도되지 않습니다.

저장된 이름을 사용하여 나중에 연결:

ssh saved-name

첫 번째 성공적인 설정 후, 저장된 자격 증명 이름을 사용하여 다시 연결하십시오.

암호화된(암호로 보호된) 개인 키로 연결:

Connect to 10.0.2.15 as ubuntu using private key ~/.ssh/id_ed25519 with passphrase mysecret

또는 도구 매개변수를 통해:

{
  "hostname": "10.0.2.15",
  "username": "ubuntu",
  "private_key_path": "~/.ssh/id_ed25519",
  "private_key_passphrase": "mysecret"
}

암호는 저장된 자격 증명과 함께 저장되므로 향후 ssh_connect_saved 호출 시 다시 입력할 필요가 없습니다. 단일 세션에 대해 저장된 값을 재정의하려면 ssh_connect_saved에서 private_key_passphrase를 계속 제공할 수 있습니다.

점프 호스트를 통해 연결:

ssh_connect 또는 ssh_save_credentials에서 jump_host 객체를 사용하십시오:

{
  "hostname": "10.0.2.15",
  "username": "ubuntu",
  "private_key_path": "~/.ssh/id_ed25519",
  "jump_host": {
    "hostname": "203.0.113.10",
    "username": "bastion",
    "private_key_path": "~/.ssh/id_ed25519",
    "port": 22
  }
}

점프 호스트 키도 암호로 보호될 수 있습니다. jump_host 객체 내에 private_key_passphrase를 추가하십시오.

이것은 대상 호스트에 대한 기본 SSH 터널을 사용하며, 저장된 자격 증명은 동일한 점프 호스트 구성을 유지합니다. 재사용 가능한 저장된 자격 증명의 경우, 점프 호스트는 비밀번호 대신 private_key_path를 사용해야 합니다.

명령 실행:

List files in /home directory on my server
Run 'top' command on the remote server
Execute script.py and monitor its log

파일 전송:

Upload local file.txt to /home/user/ on the server
Download /var/log/app.log from the server

연결 상태 및 인벤토리:

Check health of all SSH connections
Show me all active SSH connections

요구 사항

• Python 3.10+

• paramiko

• mcp

최신 업데이트

버전 1.0.3은 저장된 자격 증명에 개인 키 암호를 유지합니다:

• ssh_connect 또는 ssh_save_credentials를 통해 저장할 때 private_key_passphrase가 자격 증명 파일에 저장됩니다.

• ssh_connect_saved는 저장된 암호를 자동으로 사용하므로 모든 호출 시 제공할 필요가 없습니다.

• ssh_connect_saved에서 private_key_passphrase를 제공하면 해당 세션에 대해서만 저장된 값이 재정의됩니다.

• ssh_list_saved_credentials는 암호가 저장된 경우 private key (passphrase saved)를 표시합니다.

버전 1.0.2는 암호로 보호된(암호화된) 개인 키에 대한 지원을 추가합니다:

• ssh_connect, ssh_connect_saved 및 ssh_save_credentials에서 private_key_passphrase 허용

• 대상 호스트 키와 점프 호스트 키 모두에 적용

• 키가 암호화되어 있지만 암호가 제공되지 않았거나 암호가 틀린 경우 명확한 오류 메시지 표시

버전 1.0.1은 더 안전하고 실용적인 일상적인 SSH 워크플로우를 추가합니다:

• 직접 로그인은 기본적으로 재사용 가능한 자격 증명을 저장하지만, save_credentials=false를 사용하면 비밀번호 세션에 대해서도 깔끔하게 제외할 수 있습니다.

• 저장된 자격 증명 흐름에는 이제 연결, 저장, 나열, 삭제 및 수동 키 설정 도우미가 포함됩니다.

• 호스트 신뢰 및 파일 전송 규칙이 더 엄격해졌으며, 로컬 루트 제한 및 최초 사용 시 신뢰 호스트 고정이 적용됩니다.

• 라이브 세션과 저장된 자격 증명 모두에 대해 기본 점프 호스트 연결이 지원됩니다.

• 저장된 자격 증명은 키 기반이므로 일반적인 사용 시 마스터 비밀번호가 필요하지 않습니다.

• 수동으로 저장된 개인 키 경로는 나중에 첫 연결 시가 아니라 저장할 때 유효성이 검사됩니다.

지원

협업하려면 저에게 연락하십시오.