@yawlabs/ssh-mcp

👁 npm version
👁 License: MIT

AI 도구를 위한 SSH 환경을 구축하세요. SSH 환경을 관리하고, 문제를 진단 및 해결하며, 에이전트에게 모든 것에 대한 원격 액세스 권한을 부여하는 MCP 서버입니다.

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

문제점

AI CLI 도구는 SSH가 지속적으로 끊기는 하위 프로세스에서 실행됩니다. 에이전트가 git pull을 시도하면 Permission denied (publickey) 오류가 발생합니다. 서버에 SSH로 접속하려고 하면 에이전트 소켓이 만료되어 있습니다. 배포를 시도하면 인스턴스가 재생성되어 호스트 키가 변경됩니다. 매번 AI는 무엇이 잘못되었는지 알지 못하고 헤매게 됩니다.

이러한 문제는 SSH 키가 필요한 모든 상황에서 발생합니다:

• Git — clone, pull, push, fetch, submodules, LFS

• 패키지 관리자 — 비공개 저장소에서의 npm install, pip install, go get, cargo, composer

• 서버 액세스 — SSH, SCP, SFTP, rsync

• 터널링 — 데이터베이스로의 포트 포워딩, SOCKS 프록시

• 배포 — Ansible, Terraform, Capistrano, 배포 스크립트

• 클라우드 — AWS EC2, GCP, Azure, DigitalOcean, 모든 VPS

ssh-mcp가 이 문제를 해결합니다. SSH 에이전트를 관리하고, 키를 로드하며, 오류 발생 시 실행 가능한 수정 명령어를 진단하고, 원격 작업을 제공합니다. 이 모든 것이 AI 에이전트가 호출할 수 있는 MCP 도구로 제공됩니다.

빠른 시작

npm install -g @yawlabs/ssh-mcp

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

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

도구

SSH 환경 관리

git, 배포, 터널링 등 모든 작업이 중단되지 않도록 로컬 SSH 설정을 수정하는 도구입니다.

진단

원격 작업

상위 수준 작업

ssh_exec를 사용하여 에이전트가 구축하는 일반적인 패턴을 래핑하여 더 빠르고 오류가 적은 도구입니다.

자동 진단

원격 작업이 실패하면 ssh-mcp가 자동으로 진단을 실행하고 오류 응답에 결과를 포함합니다. 에이전트가 별도로 ssh_diagnose를 호출할 필요가 없으며, 오류 메시지에서 바로 무엇이 잘못되었고 어떻게 수정해야 하는지 알 수 있습니다.

연결 풀링

원격 작업은 SSH 연결을 자동으로 재사용합니다. 에이전트가 동일한 호스트에 여러 번 호출하면 첫 번째 호출이 연결을 열고 후속 호출은 이를 재사용합니다. 연결은 마지막 사용 후 60초 동안 유지된 다음 자동으로 닫힙니다.

SSH 설정 지원

모든 연결은 ~/.ssh/config를 준수합니다. 호스트 별칭, 사용자 지정 포트, 사용자 이름, ID 파일 및 ProxyJump 설정이 자동으로 사용됩니다. SSH 설정에 Host myserver가 구성되어 있다면 host: "myserver"만 전달하면 ssh-mcp가 모든 것을 해결합니다.

ProxyJump / 배스천 호스트는 자동으로 지원됩니다. SSH 설정에 호스트에 대한 ProxyJump bastion이 있는 경우, ssh-mcp는 배스천을 통해 투명하게 연결합니다. 체인 프록시도 작동합니다.

호스트 키 확인

모든 원격 작업은 서버의 호스트 키를 ~/.ssh/known_hosts와 비교하여 확인합니다:

• 알려진 호스트, 키 일치 — 수락.

• 알려진 호스트, 키 변경됨 — 거부 (MITM 보호).

• 알려지지 않은 호스트 — 첫 연결 시 수락 (TOFU). 향후 불일치 감지를 위해 키를 고정하려면 ssh_known_hosts_fix를 사용하세요.

더 엄격한 환경의 경우 SSH_MCP_STRICT_HOST_KEY=1을 설정하여 알려지지 않은 호스트를 거부하세요. 먼저 ssh_known_hosts_fix를 사용하여 명시적으로 추가하십시오.

진단 도구(ssh_test, ssh_diagnose)는 프로브 명령에 StrictHostKeyChecking=no를 사용합니다. 이러한 프로브는 echo SSH_OK만 실행하며 자격 증명이나 데이터가 전달되지 않으므로 연결 테스트에 안전합니다. 실제 작업은 항상 hostVerifier를 거칩니다.

Windows 지원

Windows에서 ssh-mcp는 OpenSSH 인증 에이전트 서비스를 자동으로 감지합니다(\.pipeopenssh-ssh-agent 명명된 파이프를 통해). SSH_AUTH_SOCK이 필요하지 않으며, OpenSSH 에이전트 서비스가 실행 중인지 확인하기만 하면 됩니다.

인증

모든 원격 작업은 연결 매개변수를 허용합니다:

인증 해결 순서: ssh-mcp는 이 목록에서 첫 번째 일치 항목을 선택하며 이후 항목으로 넘어가지 않으므로 인증 방법이 결정론적이고 예측 가능합니다.

1. 명시적 privateKeyPath

2. 명시적 password

3. ssh-agent (Unix의 SSH_AUTH_SOCK, Windows의 \.pipeopenssh-ssh-agent)

4. 호스트에 대한 ~/.ssh/config의 ID 파일

5. 기본 키 경로 (~/.ssh/id_ed25519, id_rsa, id_ecdsa)

예시 워크플로우

에이전트가 git pull을 할 수 없는 경우

Agent calls ssh_git_check → "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list → finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") → "Key loaded"
Agent calls ssh_git_check → "Git SSH authentication to github.com succeeded as username"
Agent runs git pull → works

인스턴스 재생성 후 호스트 키가 변경된 경우

Agent calls ssh_exec on server → error: "Host key verification failed"
 (auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") → "Host key refreshed"
Agent calls ssh_exec → works

새 서버에 대한 첫 연결

Agent calls ssh_test("new-server") → "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") → full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"

프로그래밍 방식 사용

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

// Fix SSH environment
const agent = ensureAgent();
console.log(agent.message);

// Check git access
const git = checkGitSsh('github.com');
console.log(git.message);

// List available keys
const keys = listSshKeys();
for (const key of keys) {
 console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}

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

// Run multiple commands with connection pooling
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r1 = await exec(client, 'uptime');
 console.log(r1.stdout);
});
// Connection stays open for 60s — next call reuses it
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r2 = await exec(client, 'df -h');
 console.log(r2.stdout);
});
pool.drain(); // close all connections when done

// Diagnose 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

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• ssh_agent_ensureA
• ssh_config_lookupA
• ssh_deleteA
• ssh_diagnoseA
• ssh_downloadB
• ssh_execA
• ssh_findB
• ssh_git_checkA