mcp-ssh-tool

GitHub CopilotおよびVS Code向けに自律的なSSH操作を提供するModel Context Protocol (MCP) SSHクライアントサーバーです。手動のプロンプトやGUI操作なしで、自然言語によるSSH自動化を実現します。

公式MCPレジストリエントリ: io.github.oaslananka/mcp-ssh-tool
レジストリメタデータ: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

クイックスタート

インストール

• グローバルインストール（推奨）: npm install -g mcp-ssh-tool

• 一回限りの実行: npx mcp-ssh-tool

MCPクライアント設定 (VS Code / Claude Desktop / その他)

MCP設定ファイル (mcp.json, .vscode/mcp.json, またはClaude DesktopのMCP設定) に以下を追加します：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

使用例

設定が完了すると、MCPクライアントで自然言語を使用できます：

• SSH接続: "Connect to server 192.168.1.100 as admin using SSH key"

• ファイル操作: "Read the content of /etc/nginx/nginx.conf on the server"

• コマンド実行: "Run 'systemctl status nginx' on the remote server"

• パッケージ管理: "Install htop package on Ubuntu server"

• サービス制御: "Restart the nginx service"

• Claude Desktop: "connect to my server and check disk usage"

• パッケージ/サービススタックのインストール: "install nginx on my remote server"

• 設定ファイルの読み込み: "read the file /etc/nginx/nginx.conf"

• サービスの再起動: "restart the nginx service"

• ログの閲覧: "list files in /var/log"

利用可能なツール

• ssh_open_session - さまざまな認証方法でSSH接続を確立

• ssh_close_session - SSHセッションを閉じる

• ssh_list_sessions - アクティブなすべてのSSHセッションを一覧表示

• ssh_ping - セッションが生存し応答可能か確認

• ssh_list_configured_hosts - ~/.ssh/config からホストを一覧表示

• ssh_resolve_host - SSH設定からホストエイリアスを解決

• proc_exec - リモートでコマンドを実行（タイムアウト指定可能）

• proc_sudo - sudo権限でコマンドを実行

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename - ファイルシステム操作

• ensure_package - present および absent 状態でのパッケージ管理

• ensure_service - restarted を含むサービス制御

• ensure_lines_in_file - present および absent 状態でのファイル行管理

• patch_apply - ファイルにパッチを適用

• os_detect - システム情報の検出

• get_metrics - JSONまたはPrometheus形式でのサーバーメトリクス

• proc_exec_stream - チャンク出力によるストリーミングコマンド実行

• file_upload, file_download - SFTPファイル転送ヘルパー

• tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list - トンネル管理

利用可能なリソース

• mcp-ssh-tool://sessions/active - JSON形式のアクティブセッション

• mcp-ssh-tool://metrics/json - JSON形式のメトリクススナップショット

• mcp-ssh-tool://metrics/prometheus - Prometheusメトリクスエクスポート

• mcp-ssh-tool://ssh-config/hosts - 解析されたローカルSSHホストエイリアス

概要

SSH MCPサーバーは、GitHub CopilotとリモートシステムをSSH経由でつなぐブリッジとして機能します。以下をサポートしています：

• 非対話型SSH操作 - プロンプトやGUI操作は不要

• 複数の認証方法 - パスワード、SSH鍵、またはSSHエージェント

• セッション管理 - TTLおよびLRUエビクションによる自動接続プーリング

• ファイルシステム操作 - SFTP経由でのリモートファイルの読み取り、書き込み、一覧表示、管理。SFTPサブシステムを公開していないホスト向けにはSSHシェルへのフォールバック機能付き

• プロセス実行 - リモートでのコマンド実行およびsudo操作

• 高度な自動化 - パッケージ管理、サービス制御、構成管理

• セキュリティ - ログ内の機密データの自動マスキング

アーキテクチャ

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

組み込み / BusyBoxターゲット

一部の組み込みターゲットはSSHコマンド実行を公開していますが、SFTPサブシステムを搭載していません。これはDropbearやBusyBoxベースのシステムで一般的です。その場合でも ssh_open_session は成功し、sftpAvailable: false を報告します。fs_read、fs_write、fs_stat、fs_list、fs_mkdirp、fs_rmrf、fs_rename などのコアファイルツールは、自動的にシェルベースの実装にフォールバックします。

インストール

前提条件

• Node.js ≥ 20 (LTS)

• ターゲットシステムへのSSHアクセス

• 認証用のSSH鍵または資格情報

npmからのインストール

npm install -g mcp-ssh-tool

ソースからのビルド

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

CLIフラグ

• --help / -h: 使用方法と例を表示。

• --version / -v: バージョンを表示。

• --stdio: stdioモードを強制（デフォルト）。

注意: これはMCP stdioサーバーです。ターミナルは対話型シェルではありません。MCPクライアント（Claude Desktop、VS Code MCPなど）を使用するか、stdio経由でJSON-RPCを送信してください。

プラットフォームに関する注意点

• Linux / macOS: 安全なクォーティングを備えたPOSIXシェルラッパーを使用。デフォルトの一時ディレクトリ: /tmp。

• Windowsターゲット: OpenSSHサーバー/エージェントが必要です。鍵の検出は C:\Users\<you>\.ssh\ をチェックします。コマンドはPowerShellで安全に実行できるようにラップされます。パッケージ/サービスヘルパーは、Windowsターゲットでは意図的に無効化されています。

• ホスト鍵: ホスト鍵のチェックはデフォルトで緩和されています。検証を強制するには STRICT_HOST_KEY_CHECKING=true を設定し、オプションで KNOWN_HOSTS_PATH を指定してください。

ChatGPT Desktop統合

クイックセットアップ

npm run setup:chatgpt

このコマンドは、ChatGPT Desktopがmcp-ssh-toolを使用するように自動的に設定します。

手動セットアップ

ChatGPT DesktopのMCP設定に追加してください：

• macOS: ~/Library/Application Support/ChatGPT/mcp.json

• Windows: %APPDATA%\ChatGPT\mcp.json

• Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

詳細な使用方法については、docs/chatgpt-usage.md を参照してください。

Codex統合

クイックセットアップ

パッケージをグローバルにインストールし、Codexに登録します：

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

グローバルインストールを避けたい場合は、npx を通じて登録できます：

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

検証

CodexがMCPサーバーを認識しているか確認します：

codex mcp list
codex mcp get ssh-mcp

コマンドが mcp-ssh-tool または npx である有効なstdioサーバーが表示されるはずです。

オプションのセキュリティ強化

Codex管理下のサーバープロセスでホスト鍵検証を強制するには：

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

サーバーを追加した後、Codexを再起動するか新しいセッションを開き、アクティブなセッションの一覧表示やSSH接続の開始など、単純なツール呼び出しを試してください。

VS Code Copilot統合

ユーザーレベル設定（推奨）

VS Codeを開き、Ctrl+Shift+P を押して "MCP: Open User Configuration" を実行します。

mcp.json に以下を追加します：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

ワークスペースレベル設定

ワークスペースに .vscode/mcp.json を作成します：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

検証

1. VS Codeを再起動

2. Copilot Chatを開く

3. SSH MCPツールが利用可能なツールリストに表示されるはずです

4. 次のプロンプトでテスト: "Connect to 192.168.1.100 as admin and run 'uname -a'"

Claude Desktop、Antigravity、およびその他のMCPクライアント

stdioサーバーを起動できるMCP互換クライアントであれば、mcp-ssh-tool を使用できます。正確な設定画面や設定ファイルはクライアントによって異なりますが、プロセスは同じです：

1. パッケージをインストール：

npm install -g mcp-ssh-tool

2. 以下を起動するstdio MCPサーバーを登録：

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

3. クライアントが servers ではなく mcpServers 形式のスキーマを使用している場合は、同等のエントリを使用してください：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Claude Desktopの場合は、MCP設定で上記のstdioコマンドパターンを使用してください。Antigravityやその他のMCPクライアントの場合は、クライアント独自のMCP設定UIまたは設定形式を使用し、同じ実行可能コマンドを指定してください。

使用例

基本的な接続とコマンド実行

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

ファイル操作

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

システム管理

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

構成管理

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

すぐに使えるプロンプトのアイデア

"connect to my server and check disk usage"

"install nginx on my remote server"

"read the file /etc/nginx/nginx.conf"

"restart the nginx service"

"list files in /var/log"

プロのヒント

• 複数のセッション: ホストまたは環境ごとに1つのセッションを開き、本番環境、ステージング環境、開発環境を切り替える際は ssh_list_sessions と ssh_ping でセッションを維持してください。

• BusyBox/Dropbear用のSFTPフォールバック: SFTPサブシステムを公開していない組み込みシステムでは、ssh_open_session が sftpAvailable: false で成功し、コアの fs_* ツールが自動的にシェルベースの実装にフォールバックします。

• ホスト鍵検証: MCPサーバー環境で STRICT_HOST_KEY_CHECKING=true を設定し、オプションで KNOWN_HOSTS_PATH を指定すると、より厳格な本番グレードのSSH検証が可能になります。

APIリファレンス

アーキテクチャ

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

新しいツールグループの追加

1. ToolProvider を実装する src/tools/<your-namespace>.provider.ts を作成

2. src/tools/index.ts に登録

3. test/unit/tools/<your-namespace>.provider.test.ts にユニットテストを追加

mcp.ts への変更は不要です。

セッションツール

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

戻り値:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• ssh_list_sessions は、残りのTTLを含むアクティブなセッションを返します。

• ssh_ping は、セッションの生存確認とレイテンシをチェックします。

• ssh_list_configured_hosts は ~/.ssh/config を読み取ります。

• ssh_resolve_host はSSHホストエイリアスを接続パラメータに展開します。

コマンドツール

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

両方とも以下を返します:

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

ファイルツール

• fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

• fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

• fs_stat は size、mtime、mode、type を返します。

• fs_list は { "entries": [...], "nextToken": "optional" } を返します。

• fs_mkdirp はディレクトリを再帰的に作成します。

• fs_rmrf はファイルまたはディレクトリを再帰的に削除します。

• fs_rename はパスの名前変更または移動を行います。

構成および自動化ツール

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state は present および absent をサポートします。

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state は started、stopped、restarted、enabled、disabled をサポートします。

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state は present および absent をサポートします。

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

リモートプラットフォーム、ディストリビューション、バージョン、パッケージマネージャー、initシステム、シェル、一時ディレクトリを返します。

get_metrics

サーバーメトリクスを返します。デフォルト出力はJSONです。オプションの { "format": "prometheus" } でPrometheusテキスト形式を出力します。

認証

サーバーは自動フォールバック付きの複数の認証方法をサポートしています：

認証戦略の優先順位

1. パスワード (提供されている場合)

2. SSH鍵 (インライン → パス → 自動検出)

3. SSHエージェント (利用可能な場合)

SSH鍵の自動検出

サーバーは以下の場所でSSH鍵を自動的に検索します：

• ~/.ssh/id_ed25519

• ~/.ssh/id_rsa

• ~/.ssh/id_ecdsa

注意: DSA鍵 (`id_dsa