fast-mcp-ssh

fast-mcp-ssh

AI エージェント向けの SSH、SFTP、永続シェル。Rust のバイナリ 1 つで動作し、ランタイムは不要です。

モデルに実際の SSH アクセスを提供する MCP サーバーです。

• ホストごとに接続を 1 つ確立し、呼び出しの間も維持します。
• cd や export の状態を保持する PTY シェル。
• cat > file の代わりに SFTP を使用し、ホスト間のコピーではディスクを経由しません。
• リモートデスクトップのスクリーンショットを取得します。
• データがマシンの外に出る前に正規表現でチェックします。
• すべての呼び出しを追記専用の監査ログに記録します。

結果は TOON 形式で返されます。表形式のデータでは、JSON よりトークン数を約 40 パーセント削減できます。

インストール

cargo install fast-mcp-ssh

または、最新リリースからビルド済みバイナリをダウンロードし、SHA256SUMS.txt と照合してください。Linux と macOS では x86_64 と aarch64、Windows では x86_64 を提供しています。

hosts.example.toml を ~/.fast-mcp-ssh/hosts.toml にコピーし、ホストの情報を入力してください。キーは ~/.fast-mcp-ssh/keys/<name> に配置します。auth には key、agent、または password を指定します。

接続設定

Claude Desktop では .mcp.json または claude_desktop_config.json を使用します。

{
  "mcpServers": {
    "ssh": {
      "type": "stdio",
      "command": "fast-mcp-ssh"
    }
  }
}

同じ設定ブロックを Claude Code、Cursor、Windsurf、Zed、VS Code Copilot、および stdio 経由で MCP を扱うほかのあらゆるクライアントで使用できます。

MCP レジストリでは、名前は mcp-name: io.github.klNuno/fast-mcp-ssh です。

ツール

[defaults] default_host を設定すると、すべてのツールで host の指定を省略できます。

グループ	ツール
実行	exec exec_batch sh interrupt	単発実行、並列一括実行、永続 PTY、Ctrl-C
ファイル	ls stat dn up cp wr mkdir rm tail	SFTP、およびウィンドウ幅を制限した tail -n / tail -F
表示	shot	リモートデスクトップのスクリーンショットを取得し、モデルに届く前に縮小します
運用	facts sys svc	キャッシュされたホスト情報、解析済みの ps / df / mem / net、systemd ユニット
セッション	hosts ping disconnect disconnect_all reload shells	ホストの検出とライフサイクル管理。reload は再起動せずに設定を切り替え、shells は名前付き PTY を閉じます
ネットワーク	forward unforward forwards	同じ接続を介したローカル TCP フォワーディング

すべてのツールには MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付与されるため、クライアントは破壊的な呼び出しを制限できます。

ホスト間コピー

cp は設定済みのホスト間でファイルを転送します。データはディスクに保存されず、モデルに届くこともありません。成功する前に両端で sha256 を比較します。ガードは転送先にも適用されるため、読み取り専用の転送先では書き込みが拒否されます。

リモートのスクリーンショット

shot は長いテキストの代わりに画像をモデルに渡します。ホストで利用可能な grim、gnome-screenshot、spectacle、ImageMagick の import、または scrot を使用し、X11 と wlroots Wayland に対応します。さらにローカルで画像を縮小するため、4K 画面でも数メガバイトのペイロードになりません。

プロトコル

ステートレス MCP（2026-07-28）と、それ以前のすべてのリビジョン（2024-11-05まで）に対応し、ピアごとに選択されます。ステートレス化により、次の3点が変更されます。

• 確認は input_required の結果として返され、クライアントが応答して再試行します（SEP-2322）。サーバーは自らリクエストを開始できなくなる場合があるためです。旧バージョンに対応するピアでは、elicitation/create が引き続き使われます。
• 長時間の呼び出しでは、ポーリング用のタスクハンドルが返されます（SEP-2663）。たとえば、60秒のタイムアウトを超える exec や、follow=true を指定した tail です。この拡張機能に対応していないクライアントでは、呼び出しは引き続きブロッキング方式です。
• tools/list はソートされるため、再起動してもバイト単位で同一になり、1時間の ttlMs も含まれます（SEP-2549）。クライアントのプロンプトキャッシュが引き続きヒットします。

シェルには影響しません。PTY は従来どおり、呼び出しの host 引数と session 引数で指定されます。これは、ステートレス方式が求める明示的なハンドルです。

セキュリティ

SSH パケットが送信される前にガードが実行されます。deny_patterns は即座に拒否し、confirm_patterns はユーザーに確認を求めます。応答できないクライアントからの要求は拒否され、read_only = true は書き込みとみなされる操作をすべてブロックします。

パスは両側で検査されます。リモート側ではキー、シャドウファイル、クラウド認証情報の読み取りが、ローカル側では ~/.bashrc や自動起動フォルダーへの書き込みが対象です。tail を含む、パスを受け取るすべてのツールで両方の検査が実行され、サーバーがパスを解決した後にも再検査されます。そのため、シンボリックリンクを使ってブロック対象をすり抜けることはできません。解決できないパスが指定された呼び出しは拒否されます。

ホストキーは固定され、デフォルトでは TOFU が使われます。strict とホストごとのフィンガープリントも利用できます。すべての呼び出しは、認証情報を伏せたうえで ~/.fast-mcp-ssh/audit.log に NDJSON 形式で記録されます。

ガードが防ぐのは事故であり、モデルを制御する敵対者ではありません。リモートアカウントには適切な権限範囲を設定してください。脅威モデルについてはSECURITY.mdを、バージョン履歴についてはCHANGELOG.mdを参照してください。

ベンチマーク

同じ Linux ホスト、同じ LAN、同じ SSH キーを使用し、Windows 11 上のクライアントから各シナリオを50回実行しました。0.5.0 で測定した中央値です。数値が小さいほど優れています。benchmark/で再現でき、未加工の実行結果はbenchmark/results/にあります。

	fast-mcp-ssh	mcp-ssh-manager	ssh-mcp-server
コールドスタート	48 ms	280 ms	260 ms
exec echo ok	2.2 ms	89.7 ms	46.7 ms
exec uname -a; whoami; pwd	3.6 ms	90.9 ms	50.6 ms
exec seq 1 5000（約29 KB）	19.6 ms	90.4 ms 1	49.2 ms
1 KB ファイルの書き込み	1.1 ms	89.9 ms	47.9 ms
1 KB ファイルの読み取り	1.7 ms	90.3 ms	48.9 ms
ツールの一覧（セッションごとに送信）	26 tools, 21.1 KB	37 tools, 39.9 KB	4 tools, 1.7 KB

どちらの代替製品も Node 製であるため、コールドスタートの約250 msはランタイムの起動にかかっています。定常状態での差は接続方式によるものです。fast-mcp-ssh はホストごとに1つの SSH セッションを保持し、呼び出しごとにチャネルを開きますが、他の2つは再接続します。書き込みは、こちらでは SFTP を使い、あちらでは cat > file のヒアドキュメントを使います。

開発

cargo install --path .        # build and install from a clone
cargo test                    # unit tests
cargo clippy --all-targets    # no warnings allowed in CI
./scripts/test-sh.ps1         # end-to-end against a real host (Windows)

MCP トランスポート以外には、標準出力へ書き込まないでください。余計な println! があると JSON-RPC ストリームが破損し、クライアントはエラーを出さずに切断されます。tracing マクロは標準エラー出力に書き込むため、安全です。

ライセンス

MIT。

Footnotes

1. mcp-ssh-manager はこの応答を12 KBに切り詰めるため、同じ出力を返しているわけではありません。ssh-mcp-server は終了コードを付けずに標準出力をそのまま返します。そのため、応答が最も短く、コマンドが失敗しても成功したように見えます。 ↩