ssh-mcp

MCP (Model Context Protocol) server that gives any MCP client (Claude Code, Claude Desktop, Cursor, etc.) a persistent SSH shell on legacy Unix hosts, with helpers for a site-specific ClearCase workflow (yuview, rel, ctco).

Features

• Persistent interactive shell per session (csh/sh), reconnected automatically on demand

• Sentinel-based exec with output capture, plus send_input for interactive prompts

• One-call connect: SSH login, view script, rel project selection, XN_HOME verification

• SFTP download_file / upload_file with MD5 verification

• ClearCase checkout (ctco)

• Credentials stored encrypted (AES-256-GCM) under ~/.ssh-mcp/

• Legacy SSH algorithm support (DH group1/group14 SHA-1, CBC ciphers, ssh-rsa/ssh-dss)

Related MCP server: MSAW

Requirements

• Node.js 18 or later

• Network access to the target SSH host

Install

The server speaks MCP over stdio. Register it with your MCP client using the command below.

Generic MCP client configuration (JSON):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "github:<owner>/ssh-mcp"]
    }
  }
}

Claude Code CLI example:

claude mcp add ssh-mcp -- npx -y github:<owner>/ssh-mcp

To run from a local clone instead of npx, install dependencies and point the client at the entry file:

npm install
node /path/to/ssh-mcp/src/index.js

Data directory

All state lives in ~/.ssh-mcp/, separate from the source tree. The directory is created with mode 0700 and files with 0600 (POSIX; Windows inherits the %USERPROFILE% ACL).

If store.key is deleted, stored passwords cannot be decrypted and must be re-entered with save_config. Move the whole directory when migrating to another machine.

Security note: the key and the ciphertext live in the same directory. This protects against a single file leaking (backups, accidental sharing), not against an attacker with access to your home directory.

Tools

Typical flow

1. save_config(...) once.

2. connect() per session; keep the returned sessionId.

3. exec(sessionId, "ctls"), exec(sessionId, "cat /vobs/..."), checkout(...).

4. close_session(sessionId) when done.

Known limitations

• Host keys are trusted on first use and pinned in ~/.ssh-mcp/known_hosts. A later mismatch is rejected; if the server key was legitimately changed, delete that host's line.

• exec waits for completion up to timeoutMs (default 30000). On timeout it sends Ctrl-C and returns the partial output with a [timed out ...] prefix. Interactive commands such as rel must go through send_input.

• SFTP runs outside the ClearCase view, so download_file / upload_file do not see VOB paths. Use exec cat / heredocs instead.

• Remote checksum uses md5sum, which may be absent on some Unix variants.

ssh-mcp (한국어)

MCP 클라이언트(Claude Code, Claude Desktop, Cursor 등)에 레거시 Unix 호스트용 지속 SSH 셸을 제공하는 MCP (Model Context Protocol) 서버입니다. 특수한 ClearCase 작업 흐름(yuview, rel, ctco)을 위한 보조 도구를 포함합니다.

기능

• 세션별 지속 인터랙티브 셸(csh/sh), 필요 시 자동 재접속

• sentinel 기반 exec 출력 캡처, 인터랙티브 프롬프트용 send_input

• connect 한 번으로 SSH 로그인, view 스크립트, rel 프로젝트 선택, XN_HOME 확인까지 수행

• MD5 검증을 포함한 SFTP download_file / upload_file

• ClearCase checkout (ctco)

• 자격증명은 ~/.ssh-mcp/ 에 AES-256-GCM 암호문으로 저장

• 레거시 SSH 알고리즘 지원 (DH group1/group14 SHA-1, CBC 암호, ssh-rsa/ssh-dss)

요구사항

• Node.js 18 이상

• 대상 SSH 호스트에 대한 네트워크 접근

설치

서버는 stdio 기반 MCP 로 동작합니다. 사용하는 MCP 클라이언트에 아래 명령을 등록합니다.

범용 MCP 클라이언트 설정 (JSON):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "github:<owner>/ssh-mcp"]
    }
  }
}

Claude Code CLI 예시:

claude mcp add ssh-mcp -- npx -y github:<owner>/ssh-mcp

npx 대신 로컬 클론에서 실행하려면 의존성을 설치한 뒤 클라이언트에 진입 파일을 지정합니다.

npm install
node /path/to/ssh-mcp/src/index.js

데이터 디렉토리

모든 상태는 소스 트리와 분리된 ~/.ssh-mcp/ 에 저장됩니다. 디렉토리는 0700, 파일은 0600 으로 생성됩니다 (POSIX 기준. Windows 는 %USERPROFILE% ACL 을 상속).

store.key 가 삭제되면 저장된 비밀번호는 복호화할 수 없으므로 save_config 로 재입력해야 합니다. 다른 PC 로 이전할 때는 디렉토리 전체를 함께 옮깁니다.

보안 유의사항: 키와 암호문이 같은 디렉토리에 있습니다. 파일 단위 유출(백업, 실수로 공유)은 막아주지만 홈 디렉토리 전체에 접근 가능한 공격자에게는 보호가 되지 않습니다.

도구

기본 흐름

1. save_config(...) 최초 1회.

2. 세션마다 connect() 호출 후 반환된 sessionId 보관.

3. exec(sessionId, "ctls"), exec(sessionId, "cat /vobs/..."), checkout(...).

4. 작업 완료 시 close_session(sessionId).

알려진 제약

• 호스트 키는 최초 접속 시 신뢰(trust on first use)하여 ~/.ssh-mcp/known_hosts 에 고정됩니다. 이후 불일치하면 접속을 거부하며, 서버 키가 정당하게 바뀐 경우 해당 호스트 줄을 삭제하십시오.

• exec 는 timeoutMs(기본 30000) 까지 완료를 기다립니다. 타임아웃 시 Ctrl-C 를 보내고 [timed out ...] 접두어와 함께 부분 출력을 반환합니다. rel 같은 인터랙티브 명령은 send_input 으로 실행해야 합니다.

• SFTP 는 ClearCase view 밖에서 동작하므로 download_file / upload_file 은 VOB 경로를 인식하지 못합니다. exec cat 또는 heredoc 을 사용하십시오.

• 원격 체크섬은 md5sum 을 사용하며 일부 Unix 변종에는 없을 수 있습니다.