@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 Authentication Agentサービスを自動的に検出します（\\.\pipe\openssh-ssh-agent 名前付きパイプ経由）。SSH_AUTH_SOCK は不要です。OpenSSHエージェントサービスが実行されていることを確認してください。

認証

すべてのリモート操作は接続パラメータを受け入れます：

認証解決順序: ssh-mcpはこのリストから最初の一致を選択し、それ以降の項目にはフォールスルーしません。これにより、認証方法が決定論的で予測可能になります。

1. 明示的な privateKeyPath

2. 明示的な password

3. ssh-agent (Unixでは SSH_AUTH_SOCK、Windowsでは \\.\pipe\openssh-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