ssh

SSH MCP サーバー

SSH エージェント認証に対応した、SSH リモートサーバー管理用の MCP（Model Context Protocol）サーバーです。

このサーバーは、パスフレーズで保護された SSH キーに対応していないという、SSH MCP サーバーによくある問題を解決します。SSH エージェント認証を使用することで、キーのパスフレーズを公開せずにリモートサーバーへ安全に接続できます。

主な機能

• SSH エージェント認証 - SSH エージェント経由で、パスフレーズで保護された SSH キーをシームレスに使用できます
• 秘密鍵ファイルのサポート - 秘密鍵ファイルを直接使用する認証方法も利用できます
• 起動時のヘルスチェック - 起動時に SSH 接続を検証し、明確なエラーメッセージを表示します
• コマンド実行 - リモートサーバーでシェルコマンドを実行します
• ファイル転送 - SFTP 経由でファイルをアップロードおよびダウンロードします
• ディレクトリ一覧表示 - リモートのファイルシステムを参照します
• ツールグループ - 利用可能なツールを制御します（readonly、write、admin）

認証の優先順位

このサーバーは複数の認証方法に対応しており、次の順序で使用します。

1. SSH エージェント（推奨） - SSH_AUTH_SOCK が設定されているか、自動検出された場合
2. 秘密鍵ファイル - SSH_PRIVATE_KEY_PATH が設定されている場合

両方の方法を同時に設定できます。SSH エージェント認証が利用可能な場合は、そちらが優先されます。秘密鍵ファイルによる認証は、フォールバックとして、またはエージェントを利用できない場合に使用されます。

機能

ツール

ツール	グループ	説明
ssh_connection_info	readonly、write、admin	設定済みの SSH 接続情報を取得します
ssh_list_directory	readonly、write、admin	リモートサーバー上のディレクトリの内容を一覧表示します
ssh_download	readonly、write、admin	SFTP 経由でリモートサーバーからファイルをダウンロードします
ssh_upload	write、admin	SFTP 経由でリモートサーバーにファイルをアップロードします
ssh_execute	admin	リモートサーバーでシェルコマンドを実行します

リソース

リソース	説明
ssh://config	SSH 接続の設定とステータス（デバッグ用）

ツールグループ

ENABLED_TOOLGROUPS 環境変数を使用して、利用可能なツールを制御します。

グループ	説明
readonly	安全な操作（接続情報、一覧表示、ダウンロード）
write	ファイルの変更（アップロード）
admin	コマンド実行を含むすべての操作

例：

• ENABLED_TOOLGROUPS="readonly" - 参照とダウンロードのみを許可します
• ENABLED_TOOLGROUPS="readonly,write" - ファイル転送を許可しますが、コマンド実行は許可しません
• 未設定 - すべてのツールを有効にします（デフォルト）

起動時のヘルスチェック

サーバーは起動時に SSH 接続のヘルスチェックを実行し、設定された認証情報とホストが有効であることを確認します。これにより、ワークフロー中に問題が判明するのではなく、設定に問題があればすぐに把握できます。

利点：

• 迅速なフィードバック：設定エラーをワークフローの途中ではなく、起動時に検出できます
• 明確なエラーメッセージ：起動に失敗した場合、よくある問題に対するヒントが表示されます
• ユーザーエクスペリエンスの向上：サーバーの稼働状況に関する曖昧さを解消します

設定：

• SKIP_HEALTH_CHECKS=true - ヘルスチェックをスキップします（遅延接続を行う場合に便利です）
• HEALTH_CHECK_TIMEOUT=10000 - ヘルスチェックのタイムアウトを設定します（デフォルト：10 秒）

次の問題に対するヒントが表示されます：

• 認証エラー（SSH キーが読み込まれていない、キーが間違っている）
• 接続タイムアウト（ホストに到達できない）
• 接続拒否（SSH サーバーが起動していない）
• DNS 解決エラー（ホスト名が無効）

クイックスタート

インストール

npx ssh-agent-mcp-server

または、グローバルにインストールします。

npm install -g ssh-agent-mcp-server

設定

環境変数

変数	必須	説明	デフォルト
SSH_HOST	はい	SSH サーバーのホスト名または IP アドレス	-
SSH_USERNAME	はい	SSH 認証に使用するユーザー名	-
SSH_PORT	いいえ	SSH ポート番号	22
SSH_AUTH_SOCK	いいえ	SSH エージェントソケットへのパス	自動検出
SSH_PRIVATE_KEY_PATH	いいえ	秘密鍵ファイルへのパス	-
SSH_PASSPHRASE	いいえ	暗号化された秘密鍵のパスフレーズ	-
SSH_TIMEOUT	いいえ	接続タイムアウト（ミリ秒）	30000
SSH_COMMAND_TIMEOUT	いいえ	コマンドのデフォルトアクティビティタイムアウト（ミリ秒）	60000
ENABLED_TOOLGROUPS	いいえ	カンマ区切りのツールグループ	すべて有効
SKIP_HEALTH_CHECKS	いいえ	起動時の SSH 接続ヘルスチェックをスキップする	false
HEALTH_CHECK_TIMEOUT	いいえ	ヘルスチェックのタイムアウト（ミリ秒）	10000

Claude Desktop の設定

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "ssh-agent-mcp-server"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USERNAME": "deploy",
        "SSH_AUTH_SOCK": "${SSH_AUTH_SOCK}"
      }
    }
  }
}

Claude Desktop を再起動すれば、準備完了です！

SSH エージェント認証（推奨）

パスフレーズで保護された鍵には、SSH エージェント認証の使用を推奨します。

1. SSH エージェントが起動しており、鍵が読み込まれていることを確認します。

   # Check if agent is running
   ssh-add -l
   
   # If not, add your key
   ssh-add ~/.ssh/id_ed25519
   

2. SSH_AUTH_SOCK 環境変数を MCP サーバーに渡します

サーバーは認証にエージェントを自動的に使用し、パスフレーズで保護された鍵はエージェント内で安全に保たれます。

仕組み

1. パスフレーズで保護された鍵を ssh-add で SSH エージェントに読み込みます
2. エージェントは $SSH_AUTH_SOCK に Unix ソケットを公開します
3. この MCP サーバーは ssh2 ライブラリを介してそのソケットに接続します
4. エージェントは復号済みの鍵を使用して認証チャレンジに署名します
5. 秘密鍵がエージェントの外に出ることはなく、MCP サーバーが秘密鍵を見ることもありません

これは、以下の方法よりも安全です。

• パスフレーズを環境変数に保存する
• 保護されていない秘密鍵を使用する
• パスフレーズを手動で入力する

ツールの詳細

ssh_execute

リモートサーバーでコマンドを実行します。

パラメーター：

• command（必須）：実行するシェルコマンド
• cwd（任意）：作業ディレクトリ
• timeout（任意）：アクティビティタイムアウト（ミリ秒。デフォルト：60000 または SSH_COMMAND_TIMEOUT）

アクティビティベースのタイムアウト：

タイムアウトは絶対時間ではなく、アクティビティに基づきます。コマンドから stdout または stderr の出力を受信するたびにリセットされます。これにより、定期的に出力を生成する長時間実行コマンド（ビルド、デプロイ、claude -p コマンドなど）は正常に完了できる一方、アクティビティがなく停止したコマンドは引き続きタイムアウトします。

最初の出力まで時間がかかるコマンド（出力まで 10～30 秒以上かかる場合）では、次の方法を使用できます。

1. SSH_COMMAND_TIMEOUT 環境変数でデフォルトのタイムアウトを延長します
2. 特定のコマンドに、より大きな timeout パラメーターを渡します

例：

{
  "command": "ls -la /var/log",
  "cwd": "/home/user"
}

長時間実行コマンドのタイムアウトを延長する例：

{
  "command": "npm run build",
  "timeout": 300000
}

戻り値： stdout、stderr、終了コードを含む JSON

ssh_upload

SFTP 経由でリモートサーバーにファイルをアップロードします。

パラメーター：

• localPath（必須）：ローカルファイルの絶対パス
• remotePath（必須）：サーバー上の保存先パス

ssh_download

SFTP 経由でリモートサーバーからファイルをダウンロードします。

パラメーター：

• remotePath（必須）：リモートサーバー上のパス
• localPath（必須）：ローカルの保存先パス

ssh_list_directory

リモートサーバー上のディレクトリの内容を一覧表示します。

パラメーター：

• path（必須）：一覧表示するディレクトリのパス

戻り値： ファイル名、種類、サイズ、権限、更新日時を含む JSON 配列

ssh_connection_info

設定済みの SSH 接続に関する情報を取得します。

戻り値： ホスト、ポート、ユーザー名、認証情報を含む JSON

開発

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
npm run test:integration

ライセンス

MIT