TermSSH MCP

✨ TermSSH MCP を選ぶ理由

AIワークフロー向けのSSHツールのほとんどは、コマンド実行 → 出力取得 → 終了という仕組みに基づいています。

しかし、実際のタスクがインタラクティブな場合、これでは不十分です：

• インストーラーが質問をしてくる

• シェルが状態を保持する必要がある

• デバッグに複数のステップが必要

• デプロイにはアップロードとターミナル制御の両方が必要

• エージェントが状況を観察し、反応し、継続する必要がある

TermSSH MCP は、そのギャップを埋めるために構築されました。

すべてを単一のコマンドとして扱うのではなく、MCPクライアントに本格的なオペレータースタイルのワークフローを提供します：

シェルを開く → 入力を書き込む → 出力を読み取る → コンテキストを保持する → ファイルをアップロードする → 作業を継続する

🧠 何が違うのか

ターミナルファースト

インタラクティブなターミナルセッションがコアモデルであり、後付けではありません。

エージェント対応

MCPクライアント、コーディングエージェント、自動化ループ向けに設計されています。

ステートフルなワークフロー

アクティブなセッションを再利用することで、マルチステップのタスクを自然かつ確実に実行できます。

アップロード機能内蔵

スクリプト、設定、ペイロード、生成された成果物をSFTP経由で転送します。

クロスプラットフォーム

LinuxおよびWindowsのSSHターゲットで動作します。

クリーンなツールインターフェース

ターミナル制御とリモートファイル転送に特化したMCPツールを提供します。

🚀 主な機能

• インタラクティブなSSHターミナルセッション

• インクリメンタルなターミナルの読み書きフロー

• デフォルトで管理されたターミナルセッションの再利用

• オプションによる強制的なマルチセッション作成

• SFTP経由のローカルファイルアップロード

• 直接テキストおよびbase64コンテンツのアップロード

• ターミナルのリサイズサポート

• LinuxおよびWindowsのSSHターゲットサポート

• AIツール向けのMCPネイティブインターフェース

🧰 ツールセット

upload-file

SFTPを使用して、MCPホストマシンからリモートSSHサーバーへローカルファイルをアップロードします。

パラメータ

• localPath — ローカルのソースファイルパス

• remotePath — リモートホスト上の宛先パス

• createDirectories — 必要に応じて親ディレクトリを作成する

• overwrite — 既存のリモートファイルを上書きする

• mode — 0644 などのオプションのPOSIXモード

upload-content

直接テキストまたはbase64コンテンツをリモートサーバーにアップロードします。

パラメータ

• content — 生テキストまたはbase64ペイロード

• encoding — utf8 または base64

• remotePath — リモートホスト上の宛先パス

• createDirectories — 必要に応じて親ディレクトリを作成する

• overwrite — 既存のリモートファイルを上書きする

• mode — 0644 などのオプションのPOSIXモード

terminal-start

インタラクティブなリモートターミナルセッションを開始します。

パラメータ

• cwd — シェル起動後のオプションの作業ディレクトリ

• shell — オプションのシェルバイナリ

• platformHint — auto、linux、または windows

• elevated — 設定されている場合に su 昇格を試みる

• cols — ターミナルの幅

• rows — ターミナルの高さ

• env — オプションの環境変数

• multiSession — 既存のセッションを再利用せず、新しい管理セッションを強制的に作成する場合は true に設定

terminal-write

アクティブなターミナルセッションに入力を書き込みます。

パラメータ

• sessionId — ターゲットセッションID

• input — 送信するテキスト

• appendNewline — 必要に応じて自動的に改行を追加する

terminal-read

ターミナルセッションからバッファリングされた出力を読み取ります。

パラメータ

• sessionId — ターゲットセッションID

• sinceSequence — 指定されたシーケンス番号より新しい出力のみを返す

• maxChars — 返される出力のサイズを制限する

• waitForMs — オプションの短いポーリング遅延

terminal-resize

アクティブなターミナルセッションをリサイズします。

パラメータ

• sessionId — ターゲットセッションID

• cols — 新しい幅

• rows — 新しい高さ

terminal-close

ターミナルセッションをローカルで閉じます。

パラメータ

• sessionId — ターゲットセッションID

🔄 一般的なワークフロー

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

これは特に以下の場合に有効です：

• インタラクティブなパッケージインストール

• リモートセットアップおよびプロビジョニング

• 成果物アップロードを伴うデプロイメント

• 複数のステップにわたるサービスデバッグ

• コンテキストが重要なステートフルなシェルワークフロー

🛠 インストール

リポジトリのクローン

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

グローバルインストール

npm install -g termssh-mcp

⚙ 設定

必須のCLIパラメータ

• host — リモートマシンのホスト名またはIPアドレス

• user — SSHユーザー名

オプションのCLIパラメータ

• port — SSHポート、デフォルトは 22

• password — SSHパスワード

• key — SSH秘密鍵へのパス

• sudoPassword — sudo指向のワークフロー用のオプションパスワード

• suPassword — su ベースの昇格用のオプションパスワード

• timeout — SSH準備完了までのタイムアウト（ミリ秒）、デフォルトは 60000

• maxChars — コマンド長の検証制限、デフォルトは 1000。無制限モードにするには none または 0 を使用

🧩 MCP設定例

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

SSH鍵の例

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Claude Codeの例

Claude Codeにサーバーを登録します：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

SSH鍵認証を使用する場合：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

タイムアウトを延長する場合：

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 最適な用途

開発者

• AIコーディングツールからのリモートシェルアクセス

• ステートフルなデバッグセッション

• スクリプトおよび設定の配信

DevOps / インフラチーム

• サービスの調査

• デプロイメントサポート

• マルチステップのリモート操作

エージェント開発者

• ターミナルネイティブなMCPワークフロー

• 再利用可能なセッション

• 制御されたリモート自動化ループ

🏗 開発

プロジェクトのビルド：

npm run build

テストの実行：

npm test

MCP Inspectorの使用：

npm run inspect

📁 プロジェクト構造

• src/index.ts — MCPサーバーのエントリポイントとツール登録

• src/ssh-connection-manager.ts — SSH接続とターミナルのライフサイクル管理

• src/upload.ts — アップロードヘルパーとインタラクティブセッションのメタデータヘルパー

• src/core.ts — 共有検証およびSSHユーティリティのプリミティブ

• test/upload-and-terminal.test.ts — アップロード/セッションのユニットテスト

• test/maxChars.test.ts — コマンド検証のテスト

• test/smoke.ssh.test.ts — 現在のエクスポートされた動作のスモークテスト

🗺 ロードマップのアイデア

• より詳細なセッションメタデータの調査

• リモートセッションの可観測性の向上

• オプションのセッション永続化機能

• Claude CodeおよびMCPツール向けのさらなる例

• デプロイメント指向のワークフローテンプレート

🔐 セキュリティに関する注意

TermSSH MCP は、SSH経由でシステムへのリモートアクセスを提供します。 自身が所有している、または管理を明示的に許可されているインフラストラクチャでのみ使用してください。

📜 ライセンス

MITライセンスの下でリリースされています。

🤝 貢献

貢献を歓迎します。 貢献のガイドラインについては CONTRIBUTING.md を、期待される行動については CODE_OF_CONDUCT.md を参照してください。