Ssh Mcp Server

@nl4ever/sshmcp

中文文档

AI にリモートサーバーを管理させましょう。 AI アシスタントに SSH へのフルアクセスを提供する Model Context Protocol（MCP）サーバーです。自然な会話を通じて、コマンドの実行、ファイルの転送、複数サーバーの同時管理ができます。

You:   "Deploy the latest build to production server"
AI:    connects → uploads build → restarts service → verifies status

特長

• 21 個のツール — 接続、実行、アップロード、ダウンロード、ファイルの書き込みなどができます
• 接続プール — 各コマンドに server_id を指定して、複数のサーバーを同時に操作できます
• ゼロトークンのファイル転送 — SFTP のパスベース転送により、ファイルの内容が AI のコンテキストに入ることはありません
• ディレクトリのアップロード — tar.gz に自動圧縮 → アップロード → リモートで展開（多数の小さなファイルを高速に転送）
• 非同期転送＋進捗状況 — 大容量ファイルをバックグラウンドで転送し、進捗状況をリアルタイムで追跡します
• クイック接続 — 設定を保存せずに一時接続し、host:port を一時 ID として返します
• SOCKS4/5 プロキシ — 接続ごとにプロキシを設定できます
• ジャンプホスト — SSH ProxyJump を使って踏み台／ゲートウェイにアクセスできます
• 複数の認証方式 — パスワード、秘密鍵、ssh-agent、キーボードインタラクティブ（OTP/2FA）

クイックスタート

グローバルにインストール

npm install -g @nl4ever/sshmcp

Claude Code に追加

claude mcp add sshmcp sshmcp

Claude Desktop に追加

claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": ["-y", "@nl4ever/sshmcp"]
    }
  }
}

Cursor に追加

「Settings → MCP Servers → Add」に進みます。

{
  "sshmcp": {
    "command": "npx",
    "args": ["-y", "@nl4ever/sshmcp"]
  }
}

ツールの概要

接続管理

ツール	説明
list_servers	設定済みのすべてのサーバーとアクティブな接続を一覧表示します
get_server	サーバー設定の詳細を表示します
add_server	サーバー設定を追加／更新します（パスワード、鍵、エージェント、OTP）
update_server	サーバー設定を変更します（変更したいフィールドのみ指定します）
delete_server	サーバーを削除します
rename_server	サーバー ID の名前を変更します
connect	手動で接続します（通常は不要です。ツールが自動的に接続します）
quick_connect	一時接続を行い、host:port を ID として返します
disconnect	指定したサーバー、またはすべての接続を切断します
test_connection	既存の接続に影響を与えずに接続をテストします

コマンド実行

ツール	説明
execute	リモートサーバーでシェルコマンドを実行します（タイムアウトを設定可能）

ファイル操作

ツール	説明
read_file	リモートファイルの内容を読み取ります（行範囲を指定可能）
write_file	リモートファイルにテキストを書き込みます
upload_file	ローカルファイルをリモートにアップロードします（非同期モード対応）
upload_directory	ディレクトリを自動圧縮 → 転送 → 展開してアップロードします
download_file	リモートファイルをローカルにダウンロードします（非同期モード対応）
download_directory	ディレクトリをリモートで圧縮 → 転送 → ローカルで展開してダウンロードします
transfer_status	非同期転送の進捗状況（サイズ／速度／ETA）を確認します

プロキシ管理

ツール	説明
list_proxies	すべての SOCKS プロキシプリセットを一覧表示します
add_proxy	SOCKS4/5 プロキシプリセットを追加します
delete_proxy	プロキシプリセットを削除します

接続プール：複数サーバーの操作

すべての操作ツールで server_id パラメーターを指定します。接続プールが接続を自動管理するため、手動で接続／切断する必要はありません。

AI: execute(server_id="prod", command="nginx -s reload")         ← auto-connects to prod
AI: execute(server_id="dev", command="tail -f /var/log/app.log") ← auto-connects to dev, prod stays
AI: execute(server_id="prod", command="curl localhost")           ← reuses prod connection

一時サーバーには quick_connect を使用します。host:port が ID として返されます。

AI: quick_connect(host="1.2.3.4", username="root", password="***")
→ "Connected: [email protected]:22, use server_id="1.2.3.4:22""

AI: execute(server_id="1.2.3.4:22", command="df -h")
AI: disconnect(server_id="1.2.3.4:22")

非同期転送（大容量ファイル）

大容量ファイルでは、処理をブロックしないようバックグラウンド転送モードを有効にします。

AI: upload_file(server_id="prod", local_path="big.tar.gz", remote_path="/data/", async_transfer=true)
→ "Background upload started: tf_1"

AI: transfer_status("tf_1")
→ "🔄 Uploading: 638.2 MB / 1.2 GB (53.2%) — 12.4 MB/s, ETA 46s"

AI: transfer_status("tf_1")
→ "✅ Upload complete: 1.2 GB, 98s, 12.3 MB/s"

小さなファイルはデフォルトで同期モードを使用するため、設定は不要です。

接続例

パスワード認証

AI: add_server(server_id="prod", name="Production", host="10.0.0.1", username="deploy", password="***")
AI: execute(server_id="prod", command="systemctl status nginx")

秘密鍵認証

AI: add_server(server_id="aws", name="AWS EC2", host="ec2-xx.compute.amazonaws.com", username="ubuntu", private_key="~/.ssh/id_rsa")

クイック接続（設定を保存しない）

AI: quick_connect(host="192.168.1.100", username="root", password="***")
→ server_id="192.168.1.100:22"

AI: execute(server_id="192.168.1.100:22", command="df -h")
AI: disconnect(server_id="192.168.1.100:22")

SOCKS5 プロキシ経由

AI: add_proxy(proxy_id="tunnel", name="SSH Tunnel", host="127.0.0.1", port=1080, type="5")
AI: add_server(server_id="internal", ..., proxy="tunnel")

ジャンプホスト経由

AI: add_server(server_id="bastion", name="Bastion", host="bastion.example.com", username="admin", private_key="~/.ssh/id_rsa")
AI: add_server(server_id="internal", name="Internal DB", host="10.0.0.5", username="dbadmin", password="***", jump_host="bastion")

設定ファイルの場所

サーバーとプロキシの設定は、次の場所に保存されます。

~/.ssh-mcp/config.json

パスワードは平文で保存されます。本番環境では、秘密鍵認証を推奨します。

要件

• Node.js >= 18
• MCP 対応クライアント（Claude Code、Claude Desktop、Cursor など）
• SSH アクセス可能なリモートサーバー

ライセンス

MIT