mcp-ssh-manager について
mcp-ssh-managerは、エージェントによる実サーバー操作を可視化し、承認したいチーム向けのSSH MCPサーバーです。コマンド、ファイル、バックアップ、ヘルスチェック、データベース操作を提供し、任意の管理画面と監査履歴も備えます。
主な機能
- 01SSH経由のコマンド実行とファイル転送
- 02データベースのバックアップとサーバーのヘルスチェック
- 03サーバーごとのリクエスト承認
- 04コマンド出力と監査履歴の表示
- 05デスクトップまたはブラウザー画面で接続を管理
活用シーン
- 01本番サーバーのリソース使用状況を確認
- 02デプロイ前にデータベースをバックアップ
- 03監視下でファイルを配置しサービスを再起動
- 04グループ内の複数サーバーを確認
MCP 対応
このMCPサーバーは、コマンド、ファイル操作、データベース照会、バックアップ、ヘルスチェック、トンネル用のSSHベースのツールをMCPクライアントに公開します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
npx -y mcp-ssh-managerSSH_CONFIG_PATHPath to a TOML file holding the server definitions. Defaults to ~/.codex/ssh-config.toml. Each server can set MODE to readonly or restricted to constrain what the agent may run.SSH_ENV_PATHPath to a .env file declaring servers as SSH_SERVER_<NAME>_HOST, _USER, _KEYPATH and friends. Defaults to a .env next to the package.ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
37掲載時のツール一覧 · 2 日前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| cwd | string | いいえ | 作業ディレクトリ(任意。設定されている場合はデフォルトを使用) |
| server | string | はい | 設定にあるサーバー名 |
| command | string | はい | 実行するコマンド |
| timeout | number | いいえ | コマンドのタイムアウト(ミリ秒)(デフォルト:120000、最大:300000) |
詳細
エージェントにシェルを渡せば、
それを使って何をするか見届けられます。
SSH 用の MCP サーバーです。 Claude Code、Claude Desktop、OpenAI Codex(または任意の MCP クライアント)に
実際のサーバーで作業させ、コマンドの実行、ファイルの移動、データベースへの問い合わせ、バックアップの作成、状態の確認を行いながら、
その作業をそばで見守ることができます。
編集なしの20秒 — フルサイズで視聴。実際の SSH と SFTP、ループバック上の使い捨てホスト3台。
問題をひと言で言うと
MCP SSH サーバーは、エージェントに渡せるツールの中で最も危険です。重要なマシン上で使えるシェルだからです。現在、エージェントが本番環境で何かを実行しても、気づくのは実行後です。気づかないことさえあります。
このサーバーなら、作業を見守り、拒否することもできます。 また、特別なことがない日には、自分で行うつもりだったサーバー作業をアシスタントに任せるための、とても優れた方法でもあります。
ワークスペースを選ぶ
デスクトップアプリ(4.0.1): 専用のランタイム、ターミナル、ファイルブラウザー、サーバー設定を備えた、1つのインストールです。Node.js や npm を別途インストールする必要はありません。ダウンロード:
| プラットフォーム | ファイル | 署名 |
|---|---|---|
| macOS、Apple シリコン/Intel | …-arm64.dmg / …-x64.dmg | Apple による署名および公証済み — 通常どおり開けます |
| Windows x64 / arm64 | …-setup.exe | 4.0.x ではコード署名されていません。 Windows に 「Windows によって PC が保護されました」 と表示されます:詳細情報 → 実行。リリースの release-manifest-win32.json に記載された SHA-256 とファイルを照合してください(ssh-manager app が自動で行います)。署名は後続のリリースで対応予定です。 |
| Linux x64 | .deb、.AppImage | 署名なし。通常、Linux パッケージは署名されていません |
すでに npm/CLI を使っていますか? npm update -g mcp-ssh-manager で 4.0.1 に更新できます。V4 エンジンはインターフェースなしで、既存の .env、TOML、またはプロセス変数から動作します。自動インポートや強制ウィザードはなく、サーバーごとに有効にしない限り、承認を求めるプロンプトも表示されません。動作がより厳格になるのは SSH ホストキーの検証です。アップグレードする前に、アップグレードとロールバックのガイドの該当セクションをお読みください。今は 3.8 を使い続ける場合は、バージョンを固定してください:npm install -g mcp-ssh-manager@3。
エンジンからアプリケーションへ、ワンステップで。 V4 エンジンがインストールされていれば、ssh-manager app はエンジンと同じバージョンのデスクトップアプリをダウンロードし、リリース情報(リリースマニフェストのサイズと SHA-256、macOS では Apple の署名と公証)と照合してからインストールし、起動します。すでにインストールされている場合は起動のみ行います。ssh-manager control のブラウザーインターフェースにも、同じ操作を行うボタンがあります。エージェントは引き続き npm エンジンを使います。アプリケーションはその上で動くウィンドウです。要求しない限り、何もダウンロードされません。
npm をまったく使わない場合。 アプリケーションにはエンジンも含まれており、AI ツールからそのエンジンを起動できます:オプション → AI ツールには Claude Code、Claude Desktop、Codex が一覧表示され、それぞれがどの ssh-manager(npm 版、アプリケーション版、または未設定)を起動するかが示されます。ワンクリックで切り替えられ、Node もターミナルも不要です。同じタブを ssh-manager control で開くと、npm ユーザーは各ツールが実際に実行しているバージョンを確認できます。切り替え時には、そのツールの ssh-manager エントリーだけが書き換えられ、環境変数は保持されます。変更はツールの次回起動時に反映されます。元に戻すのも同じワンクリックです。
更新。 アプリケーションは起動時と6時間ごとに新しいバージョンを確認し、目につく場所で知らせます:サイドバーのマーク、オプション → 更新(実行中のバージョン、提供中のバージョン、今すぐ確認ボタン、リリースノート)、およびバージョンごとに1回の通知です。ダウンロードはクリック1回で、インストールはもう1回クリックするか(再起動して更新)、終了時に行われます。npm エンジンは npm で、独自のスケジュールに従って更新されます。インターフェースの変更は、npm ユーザーには次の npm リリースで、アプリケーションユーザーには次のアプリケーションリリースで届きます。
npm ですぐに使い始める
npm install -g mcp-ssh-manager # or: brew tap bvisible/mcp-ssh-manager https://github.com/bvisible/mcp-ssh-manager && brew install ssh-manager
ssh-manager server add # guided: host, user, key or password
claude mcp add ssh-manager mcp-ssh-manager
以上です。Claude Code を再起動して、何か質問してみてください。
Codex、ソースのチェックアウト、またはプロジェクト単位のインストールを使っていますか?
OpenAI Codex — 同じインストールを行い、続けて2つのファイルを設定します。~/.codex/config.toml:
[mcp_servers.ssh-manager]
command = "mcp-ssh-manager"
env = { SSH_CONFIG_PATH = "/Users/you/.codex/ssh-config.toml" }
startup_timeout_ms = 20000
サーバーを ~/.codex/ssh-config.toml に設定します:
[ssh_servers.production]
host = "prod.example.com"
user = "admin"
key_path = "~/.ssh/id_rsa"
default_dir = "/var/www"
group = "production"
以下の内容はすべて Codex でも同じように動作します — ツールは同じ37個で、設定フィールドも同じです。
ソースからの場合:
git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager && npm install
cd cli && ./install.sh
claude mcp add ssh-manager node /absolute/path/to/mcp-ssh-manager/src/index.js
MCP エンジンのビルドは不要です。チェックアウトからインターフェース(ssh-manager control)を使うには、一度ビルドしてください:npm run build:ui(公開パッケージとデスクトップアプリには、すでに含まれています)。
スコープ — --scope project は、チームでコミットできる .mcp.json を書き込みます。--scope user は、自分がどこでも使えるようにします。
前提条件 — Linux、macOS、Windows のいずれかで動作する Node 18 以降。ssh_sync には rsync が必要です。パスワード認証で同期する場合のみ sshpass が必要です(brew install hudochenkov/sshpass/sshpass または apt-get install sshpass)。
そのまま質問するだけです
覚える構文はありません。アシスタントは37個のツールの使い方をすでに理解しているので、自分の言葉で話しかけるだけです。
| こう言うと | こうなります |
|---|---|
| 「今、本番環境が遅いのはなぜですか?」 | CPU、メモリー、ディスク、ロードアベレージ、上位プロセスを1回のラウンドトリップで確認します |
| 「デプロイ前にデータベースをバックアップしてください。」 | 保持ポリシーに従い、タイムスタンプ付きの圧縮済みMySQL/PostgreSQL/MongoDBダンプを作成します |
| 「ステージング環境のnginxエラーログを追跡してください。」 | 発生と同時にライブ出力をストリーミングします |
| 「./distをproduction:/var/wwwに転送して、nginxを再起動してください。」 | ファイルを転送してから再起動します。所有者、権限、ロールバック用コピーも処理します |
| 「どのサーバーでディスク容量が不足しそうですか?」 | グループ内のすべてのサーバーを並列で確認します |
| 「本番データベースへのトンネルを開いてください。」 | ローカルポートフォワーディングを設定するので、GUIクライアントから接続できます |
「productionタグが付いたすべてのサーバーでdocker psを実行してください。」 | 1つのコマンドをグループ全体で、順次または並列に実行します |
自分で操作したいときのためにCLIもあります。引数なしでssh-managerを実行すると、この画面が開きます。
動作を見守る — コントロールプレーン
4.0.0の新機能。 アプリケーションはオプトイン方式です。ボールトも承認機能も有効にしなければ、エンジンは3.8.xとまったく同じようにヘッドレスで動作し続けます。ホストキーの検証と復旧時の動作については、移行ガイドをご覧ください。
ssh-manager control # prints a local URL — or `ssh-manager app` for the desktop app
1つの機能を2つの形で提供します。ssh-manager controlを実行すると、追加のインストールなしでブラウザーのタブにインターフェース全体が表示されます。macOS、Windows、Linux向けのデスクトップビルドは、エンジンを内蔵した同じページなので、Nodeもnpmパッケージも必要ありません。
デスクトップビルドでは、ブラウザーのタブではできない次の2つの機能が追加されます。
- メニューバーに常駐します。 アイコンには待機中の項目数が表示され、メニューには、承認待ちの項目、現在開いているシェルとコマンド、サーバーが一覧表示されます。そのため、「何か承認待ちですか?」という確認は、ウィンドウを切り替えずに一目で済みます。ウィンドウを閉じても終了せず、メニューバーに残ります。
- アプリケーション独自の識別情報で、実際のシステム通知を送信します。 そのため、macOSやWindowsで適切に表示、振り分けされます。破壊的なリクエストは4秒後に消えず、画面に残ります。macOSでは、初めて通知が必要になったときに許可を求められます。
エージェントは一時停止して待機します。マシン、ユーザー、ツール、コマンドをすべて表示します。コマンドは折り返して表示し、省略しません。コマンドの一部しか見えない状態では、誤った内容を承認してしまうからです。何かが承認待ちになるとデスクトップ通知が届きます。気づかれないリクエストはタイムアウトして拒否されるためです。
承認はファイルではなく、サーバーごとにインターフェースから有効にします。
Servers → the server → Approval → never (default) | destructive | always
承認設定はボルトに保存され、.env やプロセス変数で上書きできません。接続情報を編集しても設定は維持されます。これにより、意図しない設定の上書きで承認ゲートが無効になるのを防ぎます。ただし、すでにローカルのユーザーアカウントまたはボルトファイルを操作できるプロセスに対するセキュリティ境界ではありません。ファイルで SSH_SERVER_*_APPROVAL を設定していた場合は、保護されない状態が黙って続くことのないよう、エンジンが起動のたびにそのことを通知します。
destructive リストは意図的に短くしています。狼少年のように何でも警告するプロンプトは、読まずにクリックされてしまい、プロンプトがないよりも悪いからです。systemctl restart では作業が中断されませんが、systemctl stop では中断されます。
承認が必要なリクエストでは、タイムアウト、ソケットへの接続不能、またはコントロールプレーンとの切断が発生すると、リクエストは拒否されます。待ち受けているプロセスがない場合は、再試行する前に ssh-manager control またはデスクトップアプリを起動してください。承認が無効なサーバーは、引き続きヘッドレスで動作します。
実行中の動作を確認する
出力は <pre> タグではなく、ターミナルエミュレーターを通して表示されます。エージェントが実行した内容は、色も含めて、自分で入力した場合に見えるものとまったく同じです。各ストリームには上限付きのスクロールバックが保持されるため、コマンドの実行中に画面を開いても、空白からではなく、それまでの出力を確認できます。
ここではディスクに一切触れません。 ストリームには、cat で表示した設定ファイルやデプロイスクリプトが出力したトークンなど、秘密情報が含まれる場合があります。そのため、内容はメモリ上に上限付きで保持され、ウィンドウを閉じると消去されます。
2つのファイルシステムを並べて表示
ファイルをドラッグすると、コントロールプレーンを通じてマシンとサーバーの間で直接転送されます。ブラウザーがファイルのバイト列を保持することはありません。これにより高速化されるだけでなく、数ギガバイトのファイルを転送する唯一の方法でもあります。
必要なときに確認するヘルス状態
バックグラウンドでは何も調査しません。 各チェックは SSH ハンドシェイクを行います。タイマーで本番環境のすべてのマシンに接続するダッシュボードは、ないほうがましです。スケジュールはボタンを押すだけです。しきい値は自由に設定でき、超過した場合は色ではなく言葉で通知されます。
どのマシンでも使えるシェル
マシンを選べば、シェルが使えます。エージェントが使うものと同じシェルを、キーボードで操作できます。日常的な用途にも便利ですし、特によく尋ねられる使い方にも役立ちます。つまり、サーバーに接続するのではなく、サーバー上でエージェントを実行することです。
このマシンも対象です。 デスクトップアプリでは、自分のコンピューター上でもシェルを開けます。ログインシェルと、そこで設定してあるすべての機能をそのまま使えるため、同じ作業のローカル側を実行するために別のウィンドウへ切り替える必要はありません。マシンの組み合わせを問わず、好きなだけシェルを開けます。それぞれが上部のタブとレールの項目として表示され、別のシェルに切り替えても実行は続きます。
その隣には、サーバーごと、またはすべてのサーバー共通で保存した、できれば再入力したくないコマンドがあります。どのシェルからでもリストから選べます。
そのほかの機能
同じページで、任意のサーバー上の対話型シェル、再入力せずリストから選べる保存済みコマンド、1つのコマンドをまとめて実行できるグループ、エージェントが実行したこととあなたが決定したことの監査証跡、登録済みのホスト鍵を確認できます。
上記のスクリーンショットはすべてデスクトップ版です。それぞれに対応するブラウザー版の画像も docs/images/ にあります。実装済みの内容と未実装の内容については、ROADMAP-V4.md をご覧ください。
デフォルトで安全
ほかの SSH MCP サーバーは、エージェントにシェルを渡し、あとは運任せにします。このサーバーは、操作にある程度の制御を加えたいはずだという前提で設計されています。
サーバーごとに操作範囲を決める
| モード | エージェントができること |
|---|---|
unrestricted (デフォルト) | すべての操作が可能です。ほかの SSH MCP サーバーと同じで、余計な手間はありません。 |
readonly | 変更を伴うツールはすべて拒否されます。デプロイ、アップロード、sudo、データベースのインポートはできません。読み取り操作は引き続き実行できます。 |
restricted | すべてのコマンドが許可パターンに一致し、かつ拒否パターンに一致しない必要があります。それ以外のコマンドは、ホストに届く前に拒否されます。 |
SSH_SERVER_PROD_MODE=readonly
SSH_SERVER_STAGING_MODE=restricted
SSH_SERVER_STAGING_ALLOW_PATTERNS=^systemctl (status|restart) myapp$;^tail -n \d+ /var/log/
SSH_SERVER_PROD_AUDIT_LOG=~/.ssh-manager/audit.jsonl
これは Claude Code の autoApprove の下に置かれる第2の制御レイヤーです。autoApprove はツールごとに許可するかどうかを決めるだけなので、ssh_execute が一度許可されると、あらゆる操作が可能になります。サードパーティーのエージェントや CI ボットと MCP を共有する場合や、クライアントのマシンで作業する場合に便利です。詳しくは docs/SECURITY_MODES.md をご覧ください。
認証情報を平文の .env から分離
ssh-manager vault import # take what you already have, encrypted
ssh-manager vault list # see it, without ever printing a secret
ssh-manager vault add prod # add one interactively
ssh-manager vault backup FILE # a copy that survives a new machine
AES-256-GCM を使用し、マスターキーは OS のキーチェーンに保存します。キーチェーンがない場合(Windows、CI、コンテナー)は、0600 のファイルに保存します。暗号化されるのはシークレットの値だけです。ホスト、ユーザー、モードは読み取り可能なままなので、ファイルの内容を確認したり、差分を取ったりできます。GCM は認証付き暗号のため、保管庫が改ざんされるとエラーになり、誤ったパスワードを本番サーバーに渡すことはありません。
キーはこのマシンに紐付いています。 保管庫を新しいノートパソコンにコピーしても、開けない暗号文になるだけです。vault backup では、自分で選んだパスフレーズで暗号化したコピーを作成できます。これにより、安全に移行できます。.env は変更されません。import によっても、インターフェースからも変更されません。また、設定の一部が .env に、残りが保管庫にある状態は、壊れているのではなく通常の状態です。アップグレードしても、それだけで何かが変わることはありません。詳しくは docs/MIGRATION.md をご覧ください。
華やかではありませんが、問題が起きやすい部分
- sudo のパスワードがリモートのコマンドラインに渡ることはありません。 SSH チャネルの stdin 経由で送信されるため、このカテゴリでよく使われる
echo "$pass" | sudo -Sのパターンとは異なり、ps、/proc/<pid>/cmdline、auditdの記録には表示されません(#34)。 - すべてのシェル引数は、単一の共通ヘルパーを通じてクォートされます。 テストでは、340 通りのビルダー × 引数 × ペイロードの組み合わせを実際のシェルで実行し、どの組み合わせも実行されないことを確認しています。
- 読み取り専用 SQL は推奨ではなく、強制されます。
ssh_db_queryはSELECT以外の内容を拒否します。 - 脆弱性は隠さず公開しています。 SECURITY.md には報告手順と、修正済みのすべてのアドバイザリーが記載されています。v3.8.6 で修正された 6 件も含まれており、その中には、接続先の SSH サーバーが引き金となり、サーバーを実行しているマシン上でコマンドインジェクションが発生する脆弱性も含まれます。
- 再現可能なインストール。 ロックファイルをコミットし、CI では
npm ciでインストールします。また、すべての依存関係が integrity ハッシュ付きで registry.npmjs.org から解決され、未レビューのインストールスクリプトがないことをテストで保証しています。
よくある質問
AI エージェントからサーバーへ安全に SSH 接続させることはできますか?
どこまで操作を許可するかを決めれば可能です。サーバーごとに読み取り専用にしたり、パターンに一致するコマンドだけを許可したり、すべてのリクエスト(または破壊的な操作だけ)を制御プレーンで承認するまで保留したりできます。認証情報は平文の .env ではなく、暗号化されたボルトに保存できます。また、すべてのコマンドと判断が記録されます。デフォルトで安全をご覧ください。
Claude Code や Codex で SSH を使うにはどうすればよいですか?
npm install -g mcp-ssh-manager を実行し、ssh-manager server add でサーバーを追加してから、claude mcp add ssh-manager mcp-ssh-manager を実行します。Codex のセットアップはこちらです。その後、「本番環境が遅いのはなぜ?」「ステージング環境の nginx エラーログを末尾から確認して」のように、自然な言葉で尋ねてください。
Cursor、Windsurf、Cline など、ほかの MCP クライアントでも動作しますか? 標準的な stdio MCP サーバーなので、どの MCP クライアントからも実行できます。このドキュメントでは Claude Code、Claude Desktop、Codex を説明し、テストしています。ほかのクライアントでは、たとえば次のように、そのクライアントが必要とする設定を追加してください。
{ "mcpServers": { "ssh-manager": { "command": "npx", "args": ["-y", "mcp-ssh-manager"] } } }
Node.js は必要ですか? npm を使う場合は必要です(Node 18 以降)。デスクトップアプリケーションには独自のランタイムとエンジンが含まれているため、インストール後、Options → AI tools から AI ツールを接続すれば、Node も npm も必要ありません。
ほかの SSH MCP サーバーとは何が違いますか?
多くのサーバーでは、エージェントにシェルを渡します。このサーバーでは、サーバーごとに操作範囲を選択でき、リクエストを承認まで保留でき、監査記録も保持できます。また、すべてを確認できるデスクトップアプリとブラウザーインターフェースもあります。必要であれば、.env ファイルまたは TOML ファイルから設定するシンプルなエンジンとして、それらの機能を使わずに実行することもできます。
パスワードやキーはどこに保存されますか?
キーファイルは元の場所に保存されたままです。保存したパスワードやパスフレーズは、.env ではなく暗号化されたボルト(AES-256-GCM を使用し、キーはオペレーティングシステムのキーチェーンに保存)に保存できます。
無料ですか? はい。MIT ライセンスです。ソースコードはこちらにあり、パッケージは npm、デスクトップアプリはリリースページで公開されています。
リファレンス
全 37 個のツール
コア — 常に有効
| ツール | 機能 |
|---|---|
ssh_list_servers | 設定済みのすべてのサーバーと、そのグループおよびモードを表示します |
ssh_execute | コマンドを実行します。cwd が指定されていない場合は、サーバーの DEFAULT_DIR を使用します |
ssh_upload / ssh_download | 単一のファイルを双方向に転送します |
ssh_sync | 実際の転送数を表示する、双方向の rsync です |
バックアップと復元(v2.1 以降)
| ツール | 内容 |
|---|---|
ssh_backup_create | MySQL、PostgreSQL、MongoDB、またはファイルをメタデータと保存期間の設定付きで圧縮します |
ssh_backup_list | サイズ、日付、保存期間とともに、利用可能なすべてのバックアップを一覧表示します |
ssh_backup_restore | データベースをまたぐ場合も含め、バックアップを1つ復元します |
ssh_backup_schedule | cron に登録し、自動クリーンアップを設定します |
バックアップガイドとexamples/backup-workflow.mdをご覧ください。
ヘルスチェックと監視(v2.2+)
| ツール | 内容 |
|---|---|
ssh_health_check | CPU、メモリ、ディスク、ネットワーク、稼働時間、負荷を確認し、総合判定を示します |
ssh_service_status | systemd または sysv 上の nginx、mysql、docker などを確認します |
ssh_process_manager | CPU またはメモリで並べ替えて、プロセスの一覧表示、確認、終了を行います |
ssh_alert_setup | しきい値と、しきい値を超えたときの動作を設定します |
ssh_monitor、ssh_tail | リソースのリアルタイム監視とログの追跡を行います |
データベース(v2.3+)
| ツール | 内容 |
|---|---|
ssh_db_dump | MySQL、PostgreSQL、MongoDBに対応。gzip 圧縮やテーブルの選択も可能です |
ssh_db_import | ダンプをインポートします。.gz は自動的に処理されます |
ssh_db_list | データベース、またはデータベース内のテーブルを一覧表示します |
ssh_db_query | SELECT のみ — 提案ではなく、実際に制限されています |
デプロイとセッション
| ツール | 内容 |
|---|---|
ssh_deploy | ファイルを配置し、権限設定、バックアップ、再起動も処理します — デプロイガイドをご覧ください |
ssh_execute_sudo | コマンドラインではなく標準入力からパスワードを渡して sudo を実行します |
ssh_session_* | コマンド間でコンテキストを維持する永続シェル |
ssh_tunnel_* | ローカル、リモート、SOCKS のポートフォワーディング |
整理
| ツール | 内容 |
|---|---|
ssh_alias | サーバーの短縮名 |
ssh_command_alias | 繰り返し入力するコマンドの短縮名 |
ssh_group_*、ssh_execute_group | 複数のマシンで同じ処理を実行します |
ssh_hooks | SSH 操作に関する自動化フック — エイリアスとフックをご覧ください |
ssh_profile | エイリアスとフックのセット全体を切り替えます — default、frappe、docker、nodejs、または独自のセット |
コンテキスト消費を抑える — ツールグループ
37個すべてのツールで、コンテキストを約43.5kトークン消費します。ほとんどの方はすべてを必要としません。
ssh-manager tools configure # interactive wizard
ssh-manager tools list # what's on right now
ssh-manager tools enable monitoring
ssh-manager tools disable backup
| モード | ツール | コンテキスト | 用途 |
|---|---|---|---|
| すべて (デフォルト) | 37 | ~43.5k | 全ツール |
| 最小 | 5 | ~3.5k | SSH のみ。コンテキストを92%節約できます |
| カスタム | 5–37 | 変動 | 実際に使うツール |
グループ:core(5、常時有効) · sessions(4) · monitoring(6) · backup(4) · database(4) · advanced(14)。
ツールが少ないほど、承認プロンプトも減り、起動も速くなります。ssh-manager tools export-claude を実行すると、対応する自動承認ブロックを書き出せます。
📖 完全ガイド →
別の場所からサーバーを取り込む
最初からこの方法を使う人はいません。40台のホストを登録した ~/.ssh/config があったり、FileZilla のサイトマネージャーがあったり、同僚から送られてきたスプレッドシートがあったりします。
ssh-manager import ~/.ssh/config # the format is worked out for you
ssh-manager import --from transmit # or read where a tool keeps its list
ssh-manager import --template servers.xlsx # or get a form to fill in
| 取り込み元 | 方法 |
|---|---|
スプレッドシート(.xlsx) | --template を実行すると、列を設定済みで、上書きして使えるサンプルが3つ入ったファイルが作成されます |
| CSV | カンマまたはセミコロンに対応します。Excel は地域によってどちらも出力します |
~/.ssh/config | Host、HostName、User、Port、IdentityFile、ProxyJump に対応します。ワイルドカードはスキップされ、エイリアスは1台のサーバーにまとめられます |
| FileZilla | sitemanager.xml。SFTP サイトのみです — FTP のブックマークは SSH サーバーではありません |
| PuTTY | エクスポートした .reg。.ppk キーは拒否されますが、変換用の puttygen コマンドが表示されます |
| Termius | グループを含む JSON エクスポート |
| MobaXterm | .mxtsessions。フォルダー名がグループになります |
| Transmit | お気に入りを直接読み込みます(macOS) |
パスワードが読み取られることはありません。 FileZilla では base64 でエンコードされ、Transmit ではキーチェーンに保存され、PuTTY では保存されません。他のアプリケーションのストアから認証情報をコピーするのは親切ではありません。忘れていたシークレットを、さらに気にかけなければならない場所へ移すことになります。ホスト、ユーザー、ポート、鍵のパスは引き継がれます。パスワードの入力を求められるのは、初めて接続するときの1回だけです。
逆方向の場合:
ssh-manager export servers.xlsx # or .csv, .env, .toml
エクスポートにはパスワード、パスフレーズ、sudo パスワードは含まれません。エクスポートはメールでやり取りされたり、誤ってコミットされたりするファイルだからです。
設定 — すべてのフィールド
同じローダーで読み込める、相互に置き換え可能な2つの形式があります。.env は Claude Code で一般的な形式、TOML は Codex で使う形式です(SSH_CONFIG_PATH または ~/.codex/ssh-config.toml から読み込みます)。両方を併用でき、ローダーが統合します。
SSH_SERVER_[NAME]_HOST=hostname_or_ip
SSH_SERVER_[NAME]_USER=username
SSH_SERVER_[NAME]_PASSWORD=password # or use a key
SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key
SSH_SERVER_[NAME]_CERTPATH=~/.ssh/key-cert.pub # optional: OpenSSH certificate for KEYPATH
SSH_SERVER_[NAME]_PASSPHRASE=key_passphrase # optional
SSH_SERVER_[NAME]_PORT=22 # optional
SSH_SERVER_[NAME]_DEFAULT_DIR=/var/www # optional working directory
SSH_SERVER_[NAME]_SUDO_PASSWORD=… # optional, for automated deploys
SSH_SERVER_[NAME]_DESCRIPTION=… # optional
SSH_SERVER_[NAME]_GROUP=production # optional, free-form label
SSH_SERVER_[NAME]_PLATFORM=windows # optional: linux (default) | windows
SSH_SERVER_[NAME]_PROXYJUMP=bastion # optional: another server, as jump host
SSH_SERVER_[NAME]_PROXYCOMMAND=… # optional: ncat, ssh -W, …
SSH_SERVER_[NAME]_FORWARD_AGENT=true # optional, and a real security trade-off
SSH_SERVER_[NAME]_ANNOUNCE_AGENT=true # optional: tell this host an AI agent is driving (off by default)
SSH_SERVER_[NAME]_MODE=readonly # optional: unrestricted | readonly | restricted
# Approval is NOT a field here — it is set per server from the control plane and
# stored in the vault, so that a shell on one of your machines cannot switch off
# the gate that exists to stop it.
SSH_SERVER_[NAME]_AUDIT_LOG=~/audit.jsonl # optional JSONL trail
同じ内容を TOML で記述すると、次のようになります。
[ssh_servers.production]
host = "prod.example.com"
user = "admin"
key_path = "~/.ssh/id_rsa"
port = 22
default_dir = "/var/www"
group = "production"
description = "Production server"
[ssh_servers.winhost]
host = "192.168.1.90"
user = "svc-ssh"
key_path = "~/.ssh/winhost_key"
port = 2222
platform = "windows"
[ssh_servers.internal]
host = "10.0.0.5"
user = "admin"
proxy_jump = "bastion"
OpenSSH ユーザー証明書 — 認証局を信頼するサーバー(TrustedUserCAKeys)では、CERTPATH / cert_path に、KEYPATH 用に署名された証明書(通常は <key>-cert.pub)を指定します。接続のたびに読み込まれるため、ディスク上で短期間有効な証明書を更新しても再起動は不要です。また、ファイルがない場合は、証明書なしの鍵にフォールバックせず、接続に失敗します。これは ssh2 が証明書に対応した時点で有効になります(mscdex/ssh2#1495)。それまでは、これまでどおり通常の鍵が提示されます。ssh_sync はシステムの ssh を使用し、鍵と同じ場所にある <key>-cert.pub を自動的に検出します。
読み込み順序(優先度の高い順):プロセス環境変数 → .env → 暗号化されたボルト → TOML。意図的にボルトに保存した認証情報は .env に残っているものより優先されます。1回の実行でオペレーターが上書きした値は、その両方より優先されます。
プロファイルでは、プロジェクトの種類ごとにエイリアスとフックをまとめられます。export SSH_MANAGER_PROFILE=frappe で設定するか、アシスタントから切り替えます。選択したプロファイルは ~/.ssh-manager/profile に記憶されます。default、frappe、docker、nodejs が付属しています。独自のプロファイルは profiles/ に追加できます。カスタムエイリアスとフックも ~/.ssh-manager/ に保存されるため、アップグレード後も保持されます。
直接接続できないマシンへの接続
踏み台サーバー経由 — トンネルは透過的に動作し、すべてのツールを通常どおり使えます。
SSH_SERVER_BASTION_HOST=bastion.example.com
SSH_SERVER_BASTION_USER=jumpuser
SSH_SERVER_BASTION_KEYPATH=~/.ssh/bastion_key
SSH_SERVER_PRIVATE_HOST=10.0.0.5
SSH_SERVER_PRIVATE_USER=admin
SSH_SERVER_PRIVATE_PROXYJUMP=bastion
チェーン接続にも対応しています。bastion 自体に PROXYJUMP が設定されている場合は、再帰的にたどります。循環参照は検出され、拒否されます。
SOCKS プロキシまたはカスタムコマンド経由 — ローカルで実行され、ホストに転送します。ホストとポートには %h と %p を使用します。
SSH_SERVER_SOCKS_PROXYCOMMAND="ncat --proxy 127.0.0.1:1080 --proxy-type socks5 %h %p"
SSH_SERVER_WINPROXY_PROXYCOMMAND="C:\Windows\System32\OpenSSH\ssh.exe -W %h:%p user@jump-host"
パスフレーズで保護された鍵 — 鍵を ssh-agent に読み込めば、ほかに必要な設定はありません。通常の ssh と同じ仕組みで、SSH_AUTH_SOCK が自動的に検出されます。設定に PASSPHRASE を保存する方法もありますが、あまりおすすめできません。
エージェント転送(FORWARD_AGENT=true、サーバーごとに設定し、デフォルトでは無効)を有効にすると、リモートホスト上のプロセスがローカルの鍵を使って別のホストに認証できるようになります。秘密鍵をサーバーにコピーせずに、サーバー上で SSH 経由の git clone を実行できます。
⚠️ そのホスト上で転送されたソケットを読み取れる人は、root を含め、接続が続く間、別のホストに対してあなたになりすますことができます。
ssh_config(5)の推奨どおり、信頼できるサーバーでのみ使用してください。 サーバーにエージェントが操作していることを伝える(サーバーごとにANNOUNCE_AGENT=true、または全サーバーにSSH_MANAGER_ANNOUNCE_AGENT=trueを設定します。デフォルトでは無効です)。各コマンドチャネルに AI_AGENT over SSH convention に従ってAI_AGENT=mcp-ssh-managerが含まれるため、これを記録するホストは、エージェントが操作するセッションと人が操作するセッションを区別できます。SSHではそれ以外の方法で区別できません。同じ鍵、同じユーザーをどちらも使用するためです。#84 で @mthamil107 が貢献しました。
- サーバー側で受け入れる必要があります。 標準のOpenSSHには
AcceptEnv LANG LC_*が設定されており、それ以外はすべて何も通知せず破棄されます。sshd_configにAcceptEnv AI_AGENTを追加して再読み込みすると、エージェントが実行するすべてのコマンドとシェルで$AI_AGENTが設定され、プロファイル、ラッパー、監査フックで記録できるようになります。 - 2つの理由から、デフォルトでは無効です。 アップグレードによってサーバーに届く内容が変わらないようにするためです。また、
AcceptEnvの設定にかかわらず、リクエストは すべての ホストに届きます(sshdは保存しないだけです)。そのため、管理していないホストは相手がエージェントだと知り、そのエージェント向けに出力を調整する可能性があります。グローバル設定を有効にしたまま、特定のホストで通知しないようにするにはANNOUNCE_AGENT=falseを設定します。 - 対象: コマンド、
ssh_tail --follow、インタラクティブセッション、ssh_sync(OpenSSH 3.9以降でサポートされるSendEnvを使用)。対象外: SFTP転送。変数を拒否するサーバーではssh2がSFTPセッション全体を失敗させるためです。また、環境変数のないポートフォワードも対象外です。 - 人が操作する場合は通知されません。 コントロールプレーンから行うすべての操作(シェル、ファイル、ヘルスプローブ、グループ全体へのコマンド)はあなたの操作であり、ラベルなしでサーバーに届きます。
グループ — サーバーにタグを付けるだけでグループになり、管理用の追加ファイルは不要です。
SSH_SERVER_WEB1_GROUP=production
SSH_SERVER_WEB2_GROUP=production
ssh_group_manage で作成したグループは .server-groups.json に保存され、実行設定(戦略、遅延、エラー時の停止)も保持します。同じ名前が両方の場所にある場合、メンバーシップは両方の集合になり、保存された設定が適用されます。名前の大文字と小文字は区別されません。group フィールドだけで存在するグループは ssh_group_manage では読み取り専用です。メンバーシップを変更するには、サーバーを編集してください。
問題が発生した場合
Claude Codeがフリーズする、または「Interrupted」と表示される — ほとんどの場合、コンテキストに収まらないほど出力が大きいことが原因です。出力は自動的に切り詰められ、デフォルトのタイムアウトは2分ですが、調整できます。
MCP_SSH_MAX_OUTPUT_LENGTH=5000 # default 10000 characters
MCP_SSH_DEFAULT_TIMEOUT=180000 # default 120000 ms
MCP_SSH_COMPACT_JSON=true # fewer tokens per response
また、cat huge.log より tail -n 100 huge.log を使ってください。同僚にも同じアドバイスをするでしょう。
ツールが表示されない — まず claude mcp list を実行し、その後Claude Codeを再起動してください。Claude Code内で /mcp を実行すると、現在のステータスを確認できます。
接続に失敗する — まず ssh-manager server test <name> を実行してください。DNS、ファイアウォール、認証情報のどこに問題があるかがわかります。
アクセスが拒否される — chmod 600 ~/.ssh/your_key を確認し、次にユーザー名を確認してから、そのユーザーがホストで実行を許可されている操作を確認してください。
解決できない場合は、issueを作成してください。サーバーの PLATFORM と ssh-manager server test の結果を記載してください。
既知の制限事項:
- コマンドのタイムアウトは目安です。 ssh2ではリモートプロセスを終了できません。LinuxおよびmacOSのホストでは
timeoutラッパーが適切に終了させます。Windowsホストでは、Windows版OpenSSHがこのラッパーを認識しないため、PLATFORM=windowsを設定してスキップしてください。 - パスワード認証で
ssh_syncを使うにはsshpassが必要です。 鍵を使う方がおすすめです。Windowsホストではlocal:C:\projectのようなネイティブパスを渡してください。ドライブレター形式とUNC形式のパスはMSYS2形式に変換され、すでに/c/...形式で記述されたパスは二重変換されず、そのまま渡されます。 - 接続はプールされ、再利用されます。 古くなった接続は次回の使用時に再接続されます。
ssh_connection_statusとreconnectアクションを使って、強制的に再接続できます。
プロジェクトへの取り組み
git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager && npm ci
./scripts/setup-hooks.sh # pre-commit checks, including secret detection
npm test # 43 suites
npm run typecheck # JSDoc through tsc, no build step
npm run test:all # both, plus ./scripts/validate.sh
npm run test:preview # isolated candidate fixture, restart and cleanup
ディレクトリ構成:
src/ index.js is the MCP server and its 37 tools; one module per domain
(ssh-manager, config-loader, session-manager, backup-manager,
health-monitor, database-manager, tunnel-manager, server-groups…)
cli/ the Bash CLI, plus the Node wrapper that makes it work on Windows
ui/ the control plane's React interface (v4)
desktop/ the Electron build (v4)
profiles/ frappe, docker, nodejs — and room for yours
scripts/ validation, and the rig that regenerates every screenshot and the video
docs/ guides, migration notes, security modes
プルリクエストを歓迎します。詳細はCONTRIBUTING.mdをご覧ください。デスクトップ版のリリースに必要な署名、公証、そして Mac App Store が単なる次のステップではなく別の製品である理由については、docs/DISTRIBUTION.mdをご覧ください。
この README に掲載している画像は、手作業で撮影したものではありません。scripts/demo-env.mjs が、シード済みのボルト、承認待ちの項目、ライブストリームを備えた3つの実際の ssh2 サーバーをループバック上で起動します。capture-screenshots.mjs と record-demo.mjs は DevTools プロトコル経由で Chrome を操作し、これらに接続します。frame-screenshots.py はブラウザーとアプリケーションのウィンドウを、macbook-mockup.py はノートパソコンを描画します。UI を変更したら、画像を編集するのではなく、スクリプトを再実行してください。
ヒーローアニメーションはライト版とダーク版の2種類を同梱し、<picture> を使って prefers-color-scheme に応じて切り替えます。透明な GIF 1つにするほうが簡単でしたが、GIF のアルファ値は1ビットで、透過によってフレーム間圧縮の効果が失われます。同じクリップは、透明版で 11.4 MB、単色背景版で357 KBになりました。
新着情報
4.0.1 — アプリケーションが更新を通知します。 Options → Updates、サイドバー上のマーク、バージョンごとに1回の通知により、普段開かないメニューに新しいリリースが埋もれてしまうことがなくなりました。Servers ツールバーも整理されました。インターフェースはコミットせずにパッケージ作成時にビルドされます(インストールされるものはバイト単位で同一です)。また、npm、レジストリ、GitHub の説明を V4 の内容に合わせました。エンジンの動作に変更はありません。
4.0.0 — コントロールプレーン。 エージェントがサーバー上で実行している処理とその出力を確認し、実行前に停止できます。macOS、Windows、Linux 向けのデスクトップアプリケーションは、エンジンから ssh-manager app でインストールできます。認証情報用の暗号化ボルト、サーバーごとの人による承認、リモートサーバーと並行して使えるローカルマシン上のシェルも備えています。新機能はすべてオプトインです。3.8.x から npm でアップグレードしても、従来どおり 3.8.x として動作します。レジストリからインストールするテストでこれを実証しています。このリリースでは Windows アプリケーションにコード署名されていません。変更点と以前の状態に戻す方法。
v3.8.7 — セキュリティリリースです。アップグレードしてください。 2件のアドバイザリを修正しました。サーバー名の一部またはエイリアスによって readonly モードと restricted モードを回避できていました(GHSA-mq9f-5385-rjf4)。また、ssh_backup_restore の backupId によってサーバー上でコマンドが実行されていました(GHSA-2wjh-xm9c-7qf9)。CHANGELOGをご覧ください。
v3.8.6 — セキュリティリリースです。アップグレードしてください。 6件のアドバイザリを修正しました。デフォルトの on-error フックにより、接続した SSH サーバーがローカルマシン上で任意のコマンドを実行できました。restricted モードでは行の先頭しかチェックしていませんでした。ssh_db_query で書き込みが可能でした。ホストキーの照合も行われていませんでした。CHANGELOGをご覧ください。
v3.8.5 — セキュリティリリースです。 コマンドインジェクションに関する3件のアドバイザリを修正しました。そのうち1件は readonly モードを回避できるものでした。ssh_backup_*、ssh_db_dump、ssh_service_status、または ssh_tail を使用している場合はアップグレードしてください。
readonly/restrictedを回避するRCE(GHSA-m793-whw6-f537)—ssh_service_statusとssh_tailは読み取り専用のため、制限したサーバーでも有効なままになり、引数を引用符で囲まず、ポリシーレイヤーも参照していませんでした。nginx; id > /tmp/pwnedのようなサービス名でコマンドが実行されていました。ssh_db_dump経由のRCE(GHSA-796j-h5q5-jx6p)— ダンプ後に実行されるstatで出力パスがそのまま展開されていました。v3.6.7のパッチでは、修正が1行分足りませんでした。- すべての
ssh_backup_*ツール経由のRCE(GHSA-qwwm-vrm9-4mw8)—database-manager.jsでは95か所でシェルエスケープを行っていた一方、backup-manager.jsでは9つのビルダーのいずれでもシェルエスケープが行われていませんでした。
引用符による保護を1つのモジュールに集約したため、「このビルダーは入力を引用符で囲んでいるか?」への答えは1つになりました。
ドキュメント · 変更履歴 · セキュリティポリシー · ロードマップ · イシュー
Model Context Protocolを基盤とし、難しい部分はssh2が担います。 MITライセンスです。詳しくはLICENSEをご覧ください。
Claude Codeコミュニティに❤️を込めて
リリース前の検証
V4テストガイドでは、オフラインテストスイート、実際のnpm 3.8.5 → V4 → ロールバックの確認、ブラウザでの操作フロー、プラットフォームごとのリリース条件について説明しています。 公開前に使い捨てプロファイルで実際のnpmパッケージまたはデスクトップ版の候補を確認するには、V4最終テストガイドを使用してください。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。