TermSSH MCP

✨ TermSSH MCP를 사용하는 이유

AI 워크플로우를 위한 대부분의 SSH 도구는 명령 실행 → 결과 수신 → 종료 방식으로 구축되어 있습니다.

하지만 실제 작업이 대화형일 경우 이러한 방식은 한계가 있습니다:

• 설치 프로그램이 질문을 하는 경우

• 셸이 상태를 유지해야 하는 경우

• 디버깅에 여러 단계가 필요한 경우

• 배포 시 업로드와 터미널 제어가 모두 필요한 경우

• 에이전트가 관찰하고, 반응하며, 계속 진행해야 하는 경우

TermSSH MCP는 이러한 간극을 메우기 위해 만들어졌습니다.

모든 것을 단일 명령으로 처리하는 대신, MCP 클라이언트에 실제 운영자 스타일의 워크플로우를 제공합니다:

셸 열기 → 입력 작성 → 출력 읽기 → 컨텍스트 유지 → 파일 업로드 → 작업 계속

🧠 차별점

터미널 우선

대화형 터미널 세션이 핵심 모델이며, 부가적인 기능이 아닙니다.

에이전트 준비 완료

MCP 클라이언트, 코딩 에이전트 및 자동화 루프를 위해 설계되었습니다.

상태 유지 워크플로우

활성 세션을 재사용하여 다단계 작업이 자연스럽고 안정적으로 느껴지도록 합니다.

업로드 포함

SFTP를 통해 스크립트, 설정, 페이로드 및 생성된 아티팩트를 이동합니다.

크로스 플랫폼

Linux 및 Windows SSH 대상에서 작동합니다.

깔끔한 도구 인터페이스

터미널 제어 및 원격 파일 전송을 위한 집중적인 MCP 도구입니다.

🚀 핵심 기능

• 대화형 SSH 터미널 세션

• 점진적 터미널 읽기/쓰기 흐름

• 기본적으로 관리되는 터미널 세션 재사용

• 선택적 강제 다중 세션 생성

• SFTP를 통한 로컬 파일 업로드

• 직접 텍스트 및 base64 콘텐츠 업로드

• 터미널 크기 조정 지원

• Linux 및 Windows SSH 대상 지원

• AI 도구를 위한 MCP 네이티브 인터페이스

🧰 도구 세트

upload-file

SFTP를 사용하여 MCP 호스트 머신에서 원격 SSH 서버로 로컬 파일을 업로드합니다.

매개변수

• localPath — 로컬 소스 파일 경로

• remotePath — 원격 호스트의 대상 경로

• createDirectories — 필요한 경우 누락된 상위 디렉토리 생성

• overwrite — 존재하는 경우 원격 파일 덮어쓰기

• mode — 0644와 같은 선택적 POSIX 모드

upload-content

원격 서버에 직접 텍스트 또는 base64 콘텐츠를 업로드합니다.

매개변수

• content — 원시 텍스트 또는 base64 페이로드

• encoding — utf8 또는 base64

• remotePath — 원격 호스트의 대상 경로

• createDirectories — 필요한 경우 누락된 상위 디렉토리 생성

• overwrite — 존재하는 경우 원격 파일 덮어쓰기

• mode — 0644와 같은 선택적 POSIX 모드

terminal-start

대화형 원격 터미널 세션을 시작합니다.

매개변수

• cwd — 셸 시작 후 선택적 작업 디렉토리

• shell — 선택적 셸 바이너리

• platformHint — auto, linux 또는 windows

• elevated — 구성된 경우 su 권한 상승 시도

• cols — 터미널 너비

• rows — 터미널 높이

• env — 선택적 환경 변수

• multiSession — 기존 세션을 재사용하는 대신 새로운 관리 세션을 강제로 생성하려면 true로 설정

terminal-write

활성 터미널 세션에 입력을 작성합니다.

매개변수

• sessionId — 대상 세션 ID

• input — 보낼 텍스트

• appendNewline — 필요한 경우 자동으로 줄 바꿈 추가

terminal-read

터미널 세션에서 버퍼링된 출력을 읽습니다.

매개변수

• sessionId — 대상 세션 ID

• sinceSequence — 주어진 시퀀스 번호보다 최신 출력만 반환

• maxChars — 반환된 출력 크기 제한

• waitForMs — 선택적 짧은 폴링 지연

terminal-resize

활성 터미널 세션의 크기를 조정합니다.

매개변수

• sessionId — 대상 세션 ID

• cols — 새 너비

• rows — 새 높이

terminal-close

로컬에서 터미널 세션을 닫습니다.

매개변수

• sessionId — 대상 세션 ID

🔄 일반적인 워크플로우

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

이 방식은 특히 다음에 적합합니다:

• 대화형 패키지 설치

• 원격 설정 및 프로비저닝

• 아티팩트 업로드를 포함한 배포

• 여러 단계에 걸친 서비스 디버깅

• 컨텍스트가 중요한 상태 유지 셸 워크플로우

🛠 설치

저장소 복제

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

전역 설치

npm install -g termssh-mcp

⚙ 구성

필수 CLI 매개변수

• host — 원격 머신의 호스트 이름 또는 IP 주소

• user — SSH 사용자 이름

선택적 CLI 매개변수

• port — SSH 포트, 기본값 22

• password — SSH 비밀번호

• key — 개인 SSH 키 경로

• sudoPassword — sudo 기반 워크플로우를 위한 선택적 비밀번호

• suPassword — su 기반 권한 상승을 위한 선택적 비밀번호

• timeout — SSH 준비 시간 제한(밀리초), 기본값 60000

• maxChars — 명령 길이 유효성 검사 제한, 기본값 1000; 제한 없는 모드는 none 또는 0 사용

🧩 MCP 구성 예시

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

SSH 키 예시

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Claude Code 예시

Claude Code에 서버 등록:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

SSH 키 인증 사용:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

확장된 시간 제한 사용:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 적합한 대상

개발자

• AI 코딩 도구에서 원격 셸 액세스

• 상태 유지 디버깅 세션

• 스크립트 및 설정 전달

DevOps / 인프라 팀

• 서비스 검사

• 배포 지원

• 다단계 원격 작업

에이전트 빌더

• 터미널 네이티브 MCP 워크플로우

• 재사용 가능한 세션

• 제어된 원격 자동화 루프

🏗 개발

프로젝트 빌드:

npm run build

테스트 실행:

npm test

MCP Inspector 사용:

npm run inspect

📁 프로젝트 구조

• src/index.ts — MCP 서버 진입점 및 도구 등록

• src/ssh-connection-manager.ts — SSH 연결 및 터미널 수명 주기 처리

• src/upload.ts — 업로드 도우미 및 대화형 세션 메타데이터 도우미

• src/core.ts — 공유 유효성 검사 및 SSH 유틸리티 기본 요소

• test/upload-and-terminal.test.ts — 업로드/세션 단위 테스트 범위

• test/maxChars.test.ts — 명령 유효성 검사 범위

• test/smoke.ssh.test.ts — 현재 내보낸 동작에 대한 스모크 테스트

🗺 로드맵 아이디어

• 더 풍부한 세션 메타데이터 검사

• 더 나은 원격 세션 관찰 가능성

• 선택적 세션 지속성 기능

• Claude Code 및 MCP 도구를 위한 더 많은 예시

• 배포 지향 워크플로우 템플릿

🔐 보안 참고 사항

TermSSH MCP는 SSH를 통해 시스템에 대한 원격 액세스를 제공합니다. 본인이 소유하거나 명시적으로 관리 권한이 있는 인프라에서만 사용하십시오.

📜 라이선스

MIT 라이선스에 따라 릴리스되었습니다.

🤝 기여

기여를 환영합니다. 기여 지침은 CONTRIBUTING.md를, 예상되는 행동은 CODE_OF_CONDUCT.md를 참조하십시오.