SSH Client MCP Server

SSH Client MCP サーバー

SSH Client MCP Server は、LLM やその他の MCP クライアントが SSH 経由でリモートホスト上のシェルコマンドを実行できる、ローカルの Model Context Protocol（MCP）サーバーです。Linux、macOS、Windows で動作し、接続可能な任意の SSH サーバー（Linux、macOS、OpenSSH を搭載した Windows など）を対象にできます。

テレメトリ、イントロスペクション、バックエンドの抽象化機能を備えた FastMCP ベースの機能的な MCP フレームワーク、somamcp を基盤としています。

目次

• クイックスタート
• 機能
• ツール
• インストール
• 設定
• クライアントのセットアップ
• テスト
• 開発
• 免責事項

モノレポ

このリポジトリは、3 つのパッケージで構成される pnpm モノレポです。

パッケージ	npm 名	役割
packages/core	@ssh-mcp/core（非公開）	SSH プール、tmux コマンドビルダー、認証解決機能を共有します。他のパッケージにバンドルされ、個別には公開されません。
packages/connector	ssh-client-mcp-server	単一ホスト向け MCP サーバー（元のパッケージ）です。設定済みの 1 台の SSH ホストに対して exec + tmux_* ツールを提供します。
packages/orchestrator	ssh-fleet-mcp-server	複数ホストのフリート向け MCP サーバーです。TOML フリート設定を使用し、ホストごとにルーティングされる exec + tmux_* ツールを提供します。

すべてのパッケージを対象に、検証スイート全体を実行します。

pnpm -r validate

クイックスタート

1. MCP クライアント（Claude Desktop、Cursor、Cline など）で、このサーバーを npx 経由で起動するよう設定します。詳しくはクライアントのセットアップを参照してください。
2. 対象ホスト上でシェルコマンドを実行するよう、LLM に依頼します。

グローバルインストールは不要です。npx が公開済みの最新バージョンを取得して実行します。

機能

• 単一の exec ツール — リモートホスト上でシェルコマンドを実行し、stdout を返します。stderr は構造化されたエラーとして表示されます。
• 4 種類の認証モード — パスワード、キーファイル、環境変数から取得するキー（envpkt、Vault、Doppler などによる注入）、または SSH_AUTH_SOCK（システムの ssh-agent、1Password、Bitwarden Desktop、KeePassXC）を使用できます。
• スマートなパス展開 — --key では functype-os を使用して、~、$VAR、${VAR}、相対パスを扱えます。解決できない変数は、型付きエラーを返して即座に失敗します。
• OS ユーザーへのフォールバック — --user が省略された場合、現在の OS ユーザー名が既定値になります。
• 認証のフェイルファスト — SSH キーは最初の exec 呼び出し時ではなく、サーバー起動時に読み込まれ、検証されます。
• すぐに使えるイントロスペクション — soma_health、soma_capabilities、soma_connections は somamcp によって自動登録されます。
• クロスプラットフォーム — Linux、macOS、Windows（Node 22 以降が動作する環境）で実行できます。

ツール

ツール	説明
exec	リモート SSH サーバー上でシェルコマンドを実行し、stdout を返します。
soma_health	サーバーの稼働時間、状態、アクティブなセッション数を返します。
soma_capabilities	登録済みのツール、リソース、プロンプトを列挙します。
soma_connections	ゲートウェイの接続状態を返します（ここでは未使用）。

永続セッション（tmux）

リモートのコーディングエージェントなど、長時間実行される対話型プロセスを複数回の呼び出しにわたって操作するために、サーバーは tmux ベースのツールを提供します。リモートホストに tmux をインストールしておく必要があります。

• tmux_list — 実行中の tmux セッションを一覧表示します。
• tmux_send({ session?, input, submit? }) — input を session に入力します（存在しない場合は作成します）。submit: false の場合を除き、Enter キーを押します。
• tmux_read({ session?, lines? }) — ペインの最近の出力を返します（lines のデフォルトは 200、最大は 2000）。
• tmux_keys({ session?, keys }) — 制御キーや特殊キーを送信します。例：{ keys: ["C-c"] }。

session のデフォルトは --tmux-session（デフォルトは agent）です。ヒント：tmux_read が読みやすい出力を返すよう、エージェントは全画面 TUI ではなく、行指向モードで実行してください。

インストール

npx で実行（推奨）

インストール手順は不要です。MCP クライアントが必要に応じて起動します。クライアントのセットアップを参照してください。

グローバルインストール

npm install -g ssh-client-mcp-server
# then:
ssh-client-mcp-server --host=1.2.3.4 --user=root --password=pass

ソースから（コントリビューター向け）

git clone https://github.com/jordanburke/ssh-client-mcp-server.git
cd ssh-client-mcp-server
pnpm install
pnpm build

設定

サーバーは CLI フラグから SSH 接続情報を読み取ります。

フラグ	必須	デフォルト	説明
--host	はい	—	リモート SSH サーバーのホスト名または IP アドレスです。
--user	いいえ	OS ユーザー名	SSH ユーザー名です。省略した場合は、ローカル OS ユーザー（whoami）が使用されます。
--port	いいえ	22	SSH ポートです。
--password	いいえ*	—	SSH パスワードです。
--key	いいえ*	—	SSH 秘密鍵へのパスです。~、$VAR、${VAR}、相対パスに対応しています。
--key-env	いいえ*	—	秘密鍵 PEM を格納する環境変数の名前です（例：envpkt、Vault、Doppler によって注入されたもの）。
--agent	いいえ*	—	true に設定すると、SSH_AUTH_SOCK（システムの ssh-agent、1Password、Bitwarden Desktop、KeePassXC）を使用します。

*認証の優先順位は --password → --key → --key-env → --agent です。いずれも設定されていない場合、サーバーは起動しますが、最初の exec 時に ssh2 の認証が失敗します。

パスワードマネージャーから鍵を取得する（Bitwarden／1Password／KeePassXC）

これらはそれぞれ、SSH_AUTH_SOCK を通じて SSH 鍵を利用できるようにします。保管庫のロックを解除し、エージェントが有効になっていることを確認してから、--agent=true を指定して実行してください。サーバーが秘密鍵を参照することはありません。

# verify the agent is reachable
ssh-add -l

# launch the MCP server through it
ssh-client-mcp-server --host=1.2.3.4 --user=root --agent=true

Bitwarden Desktop ≥ 2024.12 の場合：Settings → SSH agent を有効にし、macOS では launchctl getenv SSH_AUTH_SOCK が Bitwarden のソケットを指していることを確認してください。

envpkt（または環境変数を注入するツール）から鍵を取得する

PEM を envpkt.toml のシールド値として保存し、envpkt exec 経由で起動します。

envpkt exec -- ssh-client-mcp-server --host=1.2.3.4 --user=root --key-env=MY_SSH_KEY

同じ方法は、HashiCorp Vault、Doppler、Infisical、AWS Secrets Manager、または鍵を process.env に設定するラッパーでも使えます。

クライアントのセットアップ

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "ssh-client-mcp-server": {
      "command": "npx",
      "args": ["-y", "ssh-client-mcp-server", "--host=1.2.3.4", "--user=root", "--key=~/.ssh/id_ed25519"]
    }
  }
}

パスワード認証

--key 引数を --password=hunter2 に置き換えてください。これをバージョン管理に含めないようにしてください。

現在の OS ユーザーを使用する

--user を省略してください。サーバーはデフォルトでローカルのユーザー名を使用します。

その他の MCP クライアント

stdio MCP トランスポートに対応するクライアントであれば、どれでも使用できます。command／args の形式は同じです。

テスト

公開済みビルドに対して

npx @modelcontextprotocol/inspector npx ssh-client-mcp-server --host=1.2.3.4 --user=root --key=~/.ssh/id_ed25519

ローカルビルドに対して（pnpm build の実行後）

pnpm inspect

これにより、dist/index.js を指定した状態で MCP Inspector がビルドされ、起動します。

開発

すべてのツールは ts-builds に委任されています。

pnpm validate      # format → lint → typecheck → test → build
pnpm test          # vitest run
pnpm test:watch    # vitest watch mode
pnpm build         # production build to dist/
pnpm dev           # tsdown watch mode to lib/
pnpm inspect       # build + launch MCP Inspector

純粋なヘルパー（parseArgv、validateConfig、resolveAuth、effectiveUser）は src/config.ts にあり、test/config.spec.ts でテストされています（一時ファイルを使った鍵の読み込みや環境変数の展開を含む18ケース）。

免責事項

MIT License に基づいて提供されています。ご自身の責任でご利用ください。SSH ベンダーまたは MCP プロバイダーとは提携しておらず、承認も受けていません。LLM にシェルアクセスを許可する際は注意してください。コマンドを監査し、対象アカウントの権限を制限し、踏み台サーバーの使用を検討してください。

貢献

jordanburke/ssh-client-mcp-server で Issue と PR を歓迎します。提出前に pnpm validate を実行してください。