@yawlabs/ssh-mcp

Name: SSH MCP Server
Author: YawLabs

npm version License: MIT

AI 에이전트를 위한 SSH 작업. 원격 명령 실행, 파일 전송 및 문제가 무엇인지 정확히 파악하고 해결 방법을 알려주는 내장 SSH 진단 기능을 갖춘 MCP 서버입니다.

Yaw Labs에서 구축 및 유지 관리합니다.

이 도구를 사용하는 이유

원격 서버에 SSH로 접속하는 AI 에이전트는 항상 동일한 문제에 직면합니다: 죽은 ssh-agent, 잘못 로드된 키, 재생성된 인스턴스로 인한 오래된 호스트 키, 유용한 정보가 없는 권한 거부 오류 등. 대부분의 SSH MCP 서버는 단순히 ssh2를 래핑할 뿐이며 에이전트가 난해한 오류를 직접 해결하도록 합니다.

이 서버는 전체 SSH 환경(에이전트, 키, 설정, known_hosts, 연결성)을 확인하고 실행 가능한 수정 명령어를 반환하는 진단 도구인 ssh_diagnose를 포함하고 있습니다. 연결 전이나 실패 후에 사용하세요.

빠른 시작

npm install -g @yawlabs/ssh-mcp

MCP 클라이언트 설정에 추가하세요:

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-mcp"
    }
  }
}

도구

핵심 작업

도구	설명
`ssh_exec`	원격 호스트에서 명령을 실행합니다. stdout, stderr 및 종료 코드를 반환합니다.
`ssh_read_file`	SFTP를 통해 원격 호스트에서 파일을 읽습니다.
`ssh_write_file`	SFTP를 통해 원격 호스트의 파일에 내용을 씁니다.
`ssh_upload`	SFTP를 통해 로컬 파일을 원격 호스트로 업로드합니다.
`ssh_download`	원격 호스트에서 로컬 파일 시스템으로 파일을 다운로드합니다.
`ssh_ls`	원격 호스트의 디렉터리에 있는 파일 목록을 나열합니다.

진단

도구	설명
`ssh_diagnose`	SSH 연결 문제를 진단합니다. 에이전트, 키, known_hosts, SSH 설정 및 실시간 연결성을 확인합니다. 실행 가능한 수정 명령어를 반환합니다.

인증

모든 도구는 다음 연결 매개변수를 허용합니다:

매개변수	설명	기본값
`host`	SSH 호스트 이름 또는 IP (필수)	—
`port`	SSH 포트	`22`
`username`	SSH 사용자 이름	현재 사용자
`privateKeyPath`	SSH 개인 키 경로	자동 감지
`password`	SSH 비밀번호 (키 사용 권장)	—

인증 해결 순서: 명시적 키 > 명시적 비밀번호 > ssh-agent (SSH_AUTH_SOCK) > 기본 키 경로 (~/.ssh/id_ed25519, id_rsa, id_ecdsa).

진단

ssh_diagnose는 5가지 검사를 실행하고 구조화된 보고서를 반환합니다:

SSH 에이전트 — ssh-agent가 실행 중인가요? 키가 로드되었나요?
SSH 키 — ~/.ssh/에 개인 키가 존재하나요?
SSH 설정 — 이 호스트에 대한 설정 항목이 있나요? (와일드카드 지원)
Known Hosts — 호스트 키가 캐시되어 있나요?
연결성 — 실제로 연결할 수 있나요?

실패한 각 검사에는 이를 해결하기 위한 정확한 명령어가 포함되어 있습니다. 예시 출력:

SSH Diagnostic Report for dev-server:22
Overall: ERROR

[PASS] SSH Agent
  ssh-agent running with keys:
  256 SHA256:abc... user@host (ED25519)

[PASS] SSH Keys
  Found SSH keys: id_ed25519, gh_woods

[PASS] SSH Config
  SSH config for "dev-server":
  Host dev-server
    HostName 10.0.1.50
    User ec2-user

[FAIL] Known Hosts
  Host "dev-server" is not in known_hosts.

[FAIL] Connectivity
  Host key verification failed for dev-server. The host key changed (instance recreated?).

Suggested fixes:
  - Remove stale host key: ssh-keygen -R "dev-server"
  - Re-add host key: ssh-keyscan -H "dev-server" >> ~/.ssh/known_hosts

프로그래밍 방식 사용

import { connect, exec, diagnose } from '@yawlabs/ssh-mcp';

// Run a command
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();

// Diagnose connectivity issues
const report = diagnose('my-server');
console.log(report.overall); // "ok" | "warning" | "error"
for (const check of report.checks) {
  console.log(`[${check.status}] ${check.name}: ${check.message}`);
}

요구 사항

Node.js 18 이상
SSH 클라이언트 설치됨 (진단용)

라이선스

MIT

Install Server

A

security – no known vulnerabilities

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

SSH MCP Server