🔗 RemoteShell MCP

LLM이 원격 SSH 서버에서 명령을 안전하게 관리하고 실행할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다.

✨ 기능

• 🔐 안전한 자격 증명 관리 - SSH 서버 프로필을 한 번 저장하면 자격 증명을 다시 입력할 필요가 없습니다

• 💻 원격 명령 실행 - 비대화형 셸 명령을 원격으로 실행합니다

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

• 🤖 LLM 기반 - FastMCP 및 Paramiko로 구축

Related MCP server: SSH MCP Server

🚀 설치

RemoteShell은 PyPI에 배포되는 stdio MCP 서버입니다. uvx로 직접 실행하세요 — 설치 단계가 필요 없습니다. 그런 다음 서버를 AI 코딩 에이전트에 등록하세요:

Claude Code

claude mcp add remoteshell --scope user -- uvx remoteshell-mcp

Codex

codex mcp add remoteshell -- uvx remoteshell-mcp

다른 에이전트 — 해당 항목을 클릭하여 펼쳐보세요 👇

cursor mcp add remoteshell -- uvx remoteshell-mcp

~/.gemini/config/mcp_config.json(전역) 또는 .agents/mcp_config.json(프로젝트)을 편집하세요:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

또는 Antigravity TUI에서 MCP Servers 보기를 열고 /mcp 명령을 실행하세요.

opencode mcp add

local을 선택한 다음 uvx remoteshell-mcp를 입력하세요.

~/.hermes/config.yaml을 편집하세요:

mcp_servers:
  remoteshell:
    command: "uvx"
    args: ["remoteshell-mcp"]

Hermes TUI에서 /reload-mcp를 실행하여 새 서버를 적용하세요.

~/.openclaw/openclaw.json을 편집하세요:

{
  "mcp": {
    "servers": {
      "remoteshell": {
        "command": "uvx",
        "args": ["remoteshell-mcp"]
      }
    }
  }
}

또는 openclaw configure를 실행하여 대화형 마법사로 추가하세요.

MCP 클라이언트 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

📖 사용법

시작은 간단합니다! 다음 중 하나를 선택하세요:

1. 🤖 LLM이 직접 구성하도록 하기 - LLM에게 호스트, 사용자 이름, 비밀번호 등을 알려주고 서버 구성을 설정하도록 요청하세요

2. ⚙️ 수동 구성 - ~/.config/remoteshell/hosts.json의 구성 파일을 직접 편집하세요

💾 구성 및 저장

RemoteShell은 서버 구성을 안전하게 다음 위치에 저장합니다:

~/.config/remoteshell/hosts.json

🔧 구성 관리

• LLM 관리: LLM이 save_server 및 remove_server 도구를 사용하여 이 파일을 자동으로 관리합니다

• 수동 편집: 고급 구성을 위해 JSON 파일을 직접 편집할 수도 있습니다

📋 예시 구성

{
  "version": 1,
  "servers": {
    "production-server": {
      "host": "1.2.3.4",
      "user": "root",
      "port": 22,
      "auth_type": "password",
      "password": "your_secure_password",
      "last_connected": null
    },
    "staging-server": {
      "host": "staging.example.com",
      "user": "ubuntu",
      "port": 22,
      "auth_type": "private_key",
      "private_key": "~/.ssh/id_rsa",
      "last_connected": "2025-01-01T00:00:00+00:00"
    }
  }
}

🔒 보안 참고 사항

POSIX 시스템에서는 구성 파일을 보호하세요:

chmod 600 ~/.config/remoteshell/hosts.json

🛠️ 사용 가능한 도구

RemoteShell은 원격 서버 관리를 위해 다음 MCP 도구를 제공합니다:

📋 list_servers()

용도: 저장된 모든 서버 프로필과 연결 상태 및 마지막 활동을 표시합니다.

사용 시점:

• 사용자가 "서버에 연결" 또는 "머신 표시"를 요청하는 경우

• 특정 connection_id가 제공되지 않은 경우

• 사용 가능한 서버를 확인해야 하는 경우

예시: "내가 구성한 서버를 보여줘" → 저장된 모든 서버와 온라인 상태 목록을 반환합니다.

💾 save_server(connection_id, host, user, auth_type, credential, port)

용도: 인증 자격 증명으로 서버 프로필을 생성하거나 업데이트합니다.

매개변수:

• connection_id: 서버의 고유 식별자 (예: "production", "staging")

• host: 서버 호스트명 또는 IP 주소

• user: SSH 사용자 이름

• auth_type: "password" 또는 "private_key"

• credential:

  • password의 경우: 일반 텍스트 비밀번호 문자열

  • private_key의 경우: 파일 경로(예: ~/.ssh/id_rsa) 또는 PEM 키 내용

• port: SSH 포트(선택 사항; 기본값은 22이며 생략하면 기존 저장 포트를 유지합니다)

사용 시점:

• 새 서버 구성을 추가할 때

• 인증 실패 후 자격 증명을 업데이트할 때

• 서버 연결 세부 정보를 변경할 때

🗑️ remove_server(connection_id)

용도: 저장소에서 서버 프로필을 영구적으로 삭제합니다.

사용 시점:

• 사용자가 서버 제거 또는 삭제를 명시적으로 요청하는 경우

• 서버에 더 이상 접근할 수 없거나 필요하지 않은 경우

⚠️ 경고: 이 작업은 되돌릴 수 없습니다

⚡ execute_command(connection_id, command)

용도: 비대화형 셸 명령을 원격으로 실행하고 결과를 반환합니다.

반환값: stdout, stderr, exit_code

사용 시점:

• 시스템 명령, 스크립트 또는 유틸리티를 실행할 때

• 서버 상태, 디스크 사용량, 프로세스 목록을 확인할 때

• 파일 작업, 패키지 관리 등을 수행할 때

사용하지 말아야 할 경우:

• 대화형 프로그램(vim, htop, top)

• 수동 입력이 필요한 명령([Y/n] 프롬프트) - -y 같은 플래그를 사용하지 않는 한

예시: execute_command(connection_id="production", command="df -h")

📤 upload_file(connection_id, local_path, remote_path)

용도: SFTP를 통해 로컬 머신에서 원격 서버로 파일을 업로드합니다.

매개변수:

• local_path: 로컬 머신에 있는 파일의 경로

• remote_path: 원격 서버의 대상 경로

참고 사항:

• remote_path가 디렉터리인 경우 원본 파일 이름이 유지됩니다

• local_path를 생략하면 서버가 기본값을 선택하고 응답에 반환합니다

📥 download_file(connection_id, remote_path, local_path)

용도: SFTP를 통해 원격 서버에서 로컬 머신으로 파일을 다운로드합니다.

매개변수:

• remote_path: 원격 서버에 있는 파일의 경로

• local_path: 로컬 머신의 대상 경로

참고 사항:

• local_path를 생략하면 기본값은 ~/.config/remoteshell/downloads/<connection_id>/<basename>입니다

🧪 개발

로컬 개발 설정

로컬 개발에는 다음 MCP 구성을 사용하세요:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/remoteShell-mcp", "run", "remoteshell-mcp"]
    }
  }
}

테스트 실행

uv run pytest