WEB

MCP 프로토콜 이해하기: Claude Desktop과 VS Code로 SSH를 자동화하는 방법

모과나무99 2025. 6. 7. 19:06

 

Claude & VS Code와 VPS를 안전하게 연결하는 방법: SSH-MCP 마스터하기! AI 도구들이 SSH-MCP를 통해 원격 서버에 안전하고 효율적으로 접속하는 비결을 알려드립니다. Node.js 기반의 `tufantunc/SSH-MCP` 프로젝트 설치부터 실제 연동 설정까지, 이 가이드 하나로 모든 것을 해결하세요!

 

요즘 개발 환경에서 AI 도구들이 정말 큰 역할을 하잖아요? 그런데 이런 AI 도구들이 원격 서버(VPS)와 안전하고 효율적으로 소통해야 할 때, SSH 연결이 생각보다 번거로울 때가 많죠? 비밀번호 입력에, 파일 전송에… 저도 비슷한 고민을 했었는데, 드디어 해답을 찾았어요! 바로 SSH-MCP 프로젝트를 활용하는 방법이랍니다. 오늘은 특히 tufantunc/SSH-MCP 프로젝트를 중심으로, 이 강력한 도구를 어떻게 설치하고 Claude Desktop, VS Code 같은 AI 도구들과 연동하여 VPS에 안전하게 연결하는지 자세히 알려드릴게요. 저와 함께 스마트한 개발 환경을 구축해봐요!

 

SSH-MCP? Model Context Protocol이 뭐죠?

SSH-MCP는 이름에서 알 수 있듯이, SSH 연결에 Model Context Protocol (MCP)을 적용한 개념이에요. 기존의 SSH 연결은 터미널에 직접 명령어를 입력하는 방식이었다면, MCP는 마치 프로그래밍 가능한 API처럼 SSH 기능을 외부에 노출해서, 다른 애플리케이션들이 이 프로토콜을 통해 SSH 작업을 수행할 수 있게 해주는 거죠. 즉, AI 도구들이 사람이 직접 SSH 명령어를 치는 대신, 구조화된 데이터를 주고받으며 원격 서버와 상호작용할 수 있게 해준답니다.

이게 왜 중요하냐면요, Claude Desktop이나 VS Code 같은 AI 도구들이 단순히 코드를 생성하거나 분석하는 것을 넘어, 원격 서버의 파일을 읽거나, 특정 명령을 실행하고, 심지어 파일까지 업로드/다운로드하는 등 더 복잡한 작업을 수행할 수 있게 만들어주기 때문이에요. AI의 활용 범위가 훨씬 넓어지는 거죠!

 

tufantunc/SSH-MCP, 어떤 기능이 있나요?

우리가 살펴볼 `tufantunc/SSH-MCP` 프로젝트는 Node.js 기반으로, 다음과 같은 핵심 기능들을 제공하여 AI 도구와의 연동을 가능하게 합니다.

  • SSH 연결 관리: 비밀번호 및 키 기반 인증을 모두 지원하여 다양한 환경에 대응할 수 있어요.
  • 원격 명령 실행: 원격 서버에서 원하는 명령어를 실행하고, 심지어 타임아웃 처리까지 가능해서 안전하게 사용할 수 있답니다.
  • 파일 업로드 및 다운로드: SFTP 프로토콜을 통해 로컬과 원격 서버 간에 파일을 쉽고 안전하게 주고받을 수 있어요.
  • 디렉토리 목록 조회: 원격 서버의 파일 시스템을 탐색하며 필요한 파일을 쉽게 찾을 수 있게 해줍니다.
  • 보안 연결 처리: SSH의 강력한 보안 기능을 그대로 활용하여 안전한 연결을 유지합니다.
  • MCP 호환성: Claude Desktop, VS Code 등 MCP를 지원하는 다양한 AI 및 개발 도구와 연동할 수 있도록 설계되었어요.

 

사전 준비: Node.js와 Git 설치하기

이 프로젝트는 Node.js 기반이기 때문에, 여러분의 로컬 컴퓨터(클로드 데스크탑이 실행되는 환경)에 Node.js가 설치되어 있어야 합니다. Node.js 18 이상 버전을 권장해요!

  • Node.js & npm 설치 확인: 터미널을 열고 다음 명령어를 입력해 보세요.
    node -v
    npm -v
    만약 설치되어 있지 않다면, Node.js 공식 웹사이트(nodejs.org)에서 LTS 버전을 다운로드하여 설치해 주세요. npm은 Node.js 설치 시 함께 설치됩니다.
  • Git 설치 확인:
    git --version
    Git이 없다면, 운영체제에 맞춰 설치해 주세요. (예: Ubuntu - `sudo apt install git`, macOS - `brew install git`)

 

tufantunc/SSH-MCP 설치 및 빌드하기

이제 `tufantunc/SSH-MCP` 프로젝트를 여러분의 로컬 컴퓨터에 설치하고 빌드하는 과정을 알아볼게요. 제공해주신 HTML의 설치 가이드를 바탕으로 설명해 드립니다.

  1. 프로젝트 클론: 터미널을 열고 프로젝트를 다운로드할 디렉토리로 이동한 다음, 다음 명령어를 실행합니다.
    git clone https://github.com/tufantunc/ssh-mcp.git
     
  2. 디렉토리 이동: 클론한 프로젝트 디렉토리로 이동합니다.
    cd ssh-mcp
  3. 의존성 설치: 프로젝트에 필요한 Node.js 패키지들을 설치합니다.
    npm install
  4. 프로젝트 빌드: TypeScript 소스 코드를 JavaScript로 컴파일하여 실행 가능한 형태로 만듭니다.
    npm run build
    빌드가 완료되면 `build` 디렉토리 안에 컴파일된 JavaScript 파일들이 생성됩니다. 이 파일들이 실제 실행될 코드예요.
  5. 글로벌 설치 (선택 사항): 이 단계는 선택 사항이지만, 시스템의 어느 위치에서든 `ssh-mcp` 명령어를 직접 실행하고 싶을 때 유용합니다.
    npm install -g .
    이렇게 설치하면 `ssh-mcp` 명령어를 터미널에서 바로 사용할 수 있게 됩니다.

설치와 빌드가 모두 완료되었다면, 이제 `tufantunc/SSH-MCP` 서버가 여러분의 로컬 컴퓨터에서 구동될 준비를 마친 거예요!

 

Claude Desktop 및 VS Code와 연동하기 (MCP 설정)

이제 가장 중요한 단계입니다! 설치한 `tufantunc/SSH-MCP` 서버를 Claude Desktop과 VS Code가 인식하고 사용할 수 있도록 설정하는 방법이에요. 이 설정은 각 도구의 구성 파일에 `mcpServers` 항목을 추가하는 방식으로 진행됩니다.

주의하세요!
아래 설정 예시에서 `/path/to/mcp-ssh-server/build/index.js`는 실제 `SSH-MCP` 프로젝트가 설치된 경로의 `build/index.js` 파일의 절대 경로로 변경해야 합니다.

Claude Desktop 설정 예시

Claude Desktop의 설정 파일(보통 JSON 형식)에 다음 내용을 추가합니다.

{
    "mcpServers": {
        "ssh-mcp": {
            "command": "node",
            "args": [
                "C:\\ssh-mcp\\build\\index.js",
                "-y",
                "--",
                "--host=1.2.3.4",
                "--port=22",
                "--user=root",
                "--password=pass",
                "--key=path/to/key"
            ]
        }
    }
}
  • `"ssh-server"`: MCP 서버의 별명입니다. 원하는 이름으로 지정할 수 있어요.
  • `"command": "node"`: `SSH-MCP`가 Node.js로 실행된다는 것을 의미합니다.
  • `"args": ["/path/to/SSH-MCP/build/index.js"]`: `SSH-MCP` 서버의 실제 실행 파일 경로를 지정합니다.

VS Code 설정 예시

VS Code의 `settings.json` 파일에 다음 내용을 추가합니다. (VS Code에서 `Ctrl+,` 또는 `Cmd+,`를 눌러 설정 열기 -> 검색창에 `settings.json` 입력 -> `설정: JSON 편집` 선택)

{
  "mcpServers": {
    "ssh-server": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/build/index.js"]
    }
  }
}

VS Code 설정은 Claude Desktop과 유사하며, `NODE_NO_WARNINGS` 환경 변수는 필수가 아니라서 포함하지 않아도 괜찮아요.

 

SSH-MCP 명령어 활용 예시

설정이 완료되면, 이제 Claude Desktop이나 VS Code 같은 도구들이 `ssh-server`라는 이름으로 SSH-MCP 서버와 통신하며 다양한 SSH 명령을 실행할 수 있게 됩니다. 이 도구들이 내부적으로 호출하게 될 주요 명령어들은 다음과 같아요.

  • `ssh_connect`: 원격 서버에 SSH 연결을 설정할 때 사용됩니다. 이 명령을 통해 사용자 인증(비밀번호, 키)이 이루어지고 세션이 수립됩니다.
  • `ssh_exec`: 원격 서버에서 특정 명령어를 실행할 때 사용됩니다. 예를 들어, `ls -l` 이나 `sudo apt update` 같은 명령어를 AI 도구가 원격으로 실행할 수 있게 해줘요.
  • `ssh_upload_file`: 로컬 파일을 원격 서버로 업로드할 때 사용됩니다. AI가 생성한 코드를 바로 서버에 배포하거나, 설정 파일을 업데이트할 때 유용하겠죠?
  • `ssh_download_file`: 원격 서버의 파일을 로컬로 다운로드할 때 사용됩니다. 서버 로그를 분석하거나, 원격 설정 파일을 가져올 때 활용될 수 있습니다.
  • `ssh_list_directory`: 원격 서버의 특정 디렉토리 목록을 조회할 때 사용됩니다. AI가 파일 시스템을 탐색하며 필요한 정보를 얻을 때 쓰여요.
핵심은 연동!
이 명령어들은 여러분이 직접 터미널에 입력하는 것이 아니라, Claude Desktop이나 VS Code 같은 AI 도구들이 SSH-MCP 서버와 통신하는 과정에서 자동으로 호출하는 내부적인 API들이에요. 따라서 설정만 잘 해주면, AI 도구가 마치 살아있는 것처럼 VPS와 상호작용하는 모습을 볼 수 있을 거예요!

 

글의 핵심 요약

오늘은 `tufantunc/SSH-MCP` 프로젝트를 활용하여 Claude Desktop 및 VS Code와 같은 AI 도구들이 VPS에 안전하고 효율적으로 연결되는 방법을 깊이 있게 다뤄봤어요. 이 프로젝트는 MCP를 통해 SSH 제어를 API처럼 활용할 수 있게 해주는 아주 유용한 도구입니다.

  1. SSH-MCP는? Model Context Protocol을 통해 SSH 연결을 프로그램적으로 제어하여 AI 도구들이 원격 서버와 효율적으로 상호작용할 수 있게 합니다.
  2. 주요 기능: SSH 연결 관리, 원격 명령 실행, 파일 업로드/다운로드, 디렉토리 목록 조회 등 다양한 SSH 관련 기능을 제공합니다.
  3. 설치 방법: Node.js 18+ 및 Git을 사전 준비한 후, `git clone`, `npm install`, `npm run build` 명령을 통해 로컬 컴퓨터에 설치하고 빌드합니다.
  4. 도구 연동: Claude Desktop 및 VS Code의 설정 파일(`mcpServers` 항목)에 `SSH-MCP` 서버의 `command`와 `args` 경로를 정확히 지정하여 연동합니다.
  5. 활용 명령어: `ssh_connect`, `ssh_exec`, `ssh_upload_file` 등은 AI 도구가 내부적으로 SSH-MCP 서버와 통신하며 사용하는 API들입니다.

이 가이드가 여러분의 AI 개발 환경을 한층 더 스마트하고 효율적으로 만드는 데 도움이 되었기를 바랍니다. 이제 Claude Desktop이나 VS Code를 통해 VPS를 마치 내 손안에 있는 것처럼 자유롭게 다뤄보세요! 혹시 더 궁금한 점이 있다면 언제든지 댓글로 물어봐주세요~

 

자주 묻는 질문

Q: `npm install` 또는 `npm run build` 시 오류가 발생합니다.
A: 대부분 Node.js 버전이 낮거나, npm 캐시 문제, 또는 필요한 빌드 도구가 설치되지 않아서 발생하는 경우가 많아요. Node.js 18 이상 버전이 설치되어 있는지 확인하고, npm cache clean --force 후 다시 시도해 보세요. 리눅스 환경에서는 `build-essential` 패키지 등이 필요한 경우가 있습니다.
Q: Claude Desktop/VS Code 설정에서 `command`와 `args` 경로를 찾기 어렵습니다.
A: `git clone`을 실행한 디렉토리에서 pwd 명령어를 입력하여 현재 작업 디렉토리의 절대 경로를 확인하고, 그 뒤에 `/SSH-MCP/build/index.js`를 붙여주시면 됩니다. 예를 들어, /home/user/my_projects/SSH-MCP/build/index.js와 같이요.
Q: SSH-MCP를 통해 접속 시 인증 오류가 발생합니다.
A: 원격 VPS의 SSH 접속 정보(사용자 이름, 비밀번호 또는 SSH 키)가 정확한지 다시 확인해 보세요. 특히 SSH 키를 사용하는 경우, 키 파일의 경로가 올바르고 권한이 제대로 설정(일반적으로 600)되어 있는지 확인해야 합니다.

이 글이 여러분의 AI 개발 환경을 더 스마트하고 효율적으로 만드는 데 도움이 되었기를 바랍니다! 혹시 더 궁금한 점이 있다면 언제든지 댓글로 물어봐주세요~