SSH MCP サーバー (paramiko)

Paramiko ベースの SSH MCP サーバー。リモートマシンでコマンドを実行し、SFTP 経由でファイルを転送できます。環境変数 / スイッチで選択できる2つのトランスポートがあります：

• http – MCP streamable-http エンドポイントを /mcp パスに提供（ここに Cherry Studio が接続します）。さらに、ドキュメント化された OpenAPI/Swagger インターフェース（/docs, /openapi.json）も提供します。

• stdio – クラシックな MCP stdio トランスポート（ローカル起動 / docker exec 用）。

ポートに関する重要な注意： 2222 は MCP サーバーのポートであり、Cherry Studio が接続するポートです。これはリモートマシンの SSH ポートではありません。リモートマシンの SSH ポートは通常 22（SSH_PORT）です。つまり：Cherry Studio → http://<host-IP>:2222/mcp → MCP サーバー → paramiko → リモートマシンの SSH ポート 22。

利用可能な MCP ツール

ステートレス（状態を保持しない）ツール — シンプルで単発の操作

ステートフル（状態を保持する）対話型セッションツール — ライブシェル

これらはライブシェルを開いたままにし、呼び出し間で状態が維持されます（cd 後のディレクトリ変更、export した変数、対話型プロンプトへの対応：sudo パスワード、apt [Y/n] など）。

ツールの説明（docstring）は、意図的に非常に詳細でシンプルな英語の "USE THIS WHEN..." ガイドを含んでおり、そのツールをいつどのように使うのかを利用側モデルが明確に判断できるようになっています。

すべてのツールのパラメータ（host, port, username, password, private_key、private_key_path, passphrase, timeout）は次のように指定できます：

• 呼び出しごとに個別に指定するか、

• デフォルトとして .env ファイル内（SSH_* 変数）に指定します。呼び出しで指定されていない項目は、SSH_* 環境変数から取得されます。

対応している認証方式：パスワードとキー（インライン PEM またはファイルパス、オプションのパスフレーズ付き）。不明なホストキーは自動的に受け入れられます（AutoAddPolicy）ので、自動化がスムーズです。

Related MCP server: SSH MCP Server

ステートレス vs ステートフル（対話型）の使い分け

どちらをいつ使う？

• 単一の独立したコマンド（例：ls, uptime, df -h）→ ssh_execute。呼び出しのたびに新しい接続を開き、1つのコマンドを実行して閉じます。メモリはありません：cd と export は次の呼び出しまで保持されず、対話型プロンプトにも応答できません。

• 対話を伴うまたは複数ステップの処理（cd / export 後の状態維持、sudo パスワードの入力、apt [Y/n] への応答、依存しあうコマンド）→ 対話型セッション：ssh_open_session → ssh_send → ssh_read → ssh_close_session。

推奨ワークフロー（セッション）

1. ssh_open_session → session_id（と、initial_output 内のログインバナー／最初のプロンプト）が返されます。

2. ssh_send → コマンドを入力するか、プロンプトに応答します。session_id は毎回渡してください。デフォルトで Enter も送信されます。

3. ssh_read（オプション）→ 低速 / 長時間実行コマンドでは、送信せずに追加の出力を取得します。

4. ssh_close_session → 終了したらセッションを閉じてください。

ssh_list_sessions でいつでも開いているセッション（ホスト、ユーザー、アイドル時間）を確認できます。session_id を失った場合にも便利です。

例（REST エンドポイント経由）

セッションを開く：

curl -X POST http://localhost:2222/api/ssh/session/open \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret"}'
# -> {"ok":true,"session_id":"<ID>", "initial_output":"...prompt..."}

ディレクトリ変更（状態保持）：

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"cd /var/log && pwd"}'
# a következő ssh_send már a /var/log-ban futna

sudo コマンド＋パスワードプロンプトへの応答：

# 1) elindítod a sudo parancsot
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get update"}'
# 2) a kimenetben megjelenik a "[sudo] password for user:" prompt -> beküldöd a jelszót
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"my_sudo_password"}'

apt [Y/n] への応答：

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get install htop","read_timeout":5}'
# amikor jön a "Do you want to continue? [Y/n]" kérdés:
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"Y"}'

セッションを閉じる：

curl -X POST http://localhost:2222/api/ssh/session/close \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>"}'

タイムアウト / アイドル / エラー： すべてのセッション操作は、SSH_SESSION_IDLE_TIMEOUT（デフォルト600秒）を超えてアイドル状態のセッションがあることを、およびチャネルが終了したセッションを自動的に閉じます。同時に開けるセッションは最大 SSH_MAX_SESSIONS（デフォルト20）で、上限に達すると明確なエラーメッセージが表示されます。session_id が存在しなくなった場合、応答には対処方法（新しいセッションを開く、または ssh_list_sessions で確認する）が正確に示されます。

プロジェクト構成

ssh-mcp-server/
├── app/
│   ├── __init__.py
│   ├── ssh_ops.py     # paramiko SSH/SFTP műveletek (közös logika)
│   └── server.py      # MCP tool-ok + FastAPI/OpenAPI + transport választás
├── requirements.txt
├── Dockerfile
├── docker-compose.yml # 2222:2222 publikálás
├── .env.example
└── README.md

1. Docker でクイックスタート（推奨）

準備

cd ssh-mcp-server
cp .env.example .env
# szerkeszd a .env-et: add meg a távoli gép adatait (SSH_HOST, SSH_USERNAME, stb.)

ビルドと起動（HTTP モード）

docker compose up -d --build

これでサーバー/はHTTPモードで起動し、2222 ポートがホストに公開されます（ports: "2222:2222"）。

確認

curl http://localhost:2222/health
# {"status":"ok","service":"ssh-mcp-server","mcp_endpoint":"/mcp"}

• Swagger UI（ブラウザ）： http://localhost:2222/docs

• OpenAPI JSON： http://localhost:2222/openapi.json

• MCP エンドポイント（Cherry Studio）： http://<host-IP>:2222/mcp

停止

docker compose down

2. HTTP モードの手動起動（Docker なし、開発用）

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export TRANSPORT=http HOST=0.0.0.0 PORT=2222
python -m app.server

3. stdio モード

コンテナで実行中サーバーに docker exec で：

docker exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

または Docker を使わず直接：

TRANSPORT=stdio python -m app.server

4. Cherry Studio 連携

A) HTTP（streamable-http）モード – 推奨、ネットワーク経由で動作

コンテナはあなたのノートPC上の Docker で実行され、Cherry Studio はホストの IP と 2222 ポートを使用します。

1. サーバーを起動します：docker compose up -d --build

2. Docker が動いているマシン（ホスト）の IP アドレスを確認します：

   • Linux：hostname -I → 例：192.168.1.50

   • Cherry Studio が同じマシンで動いている場合、localhost / 127.0.0.1 でも問題ありません。

3. Cherry Studio でカーソル合わせに行く→ 設定（Settings） → MCP Servers → Add / 新しいサーバー。

4. 次のように入力します：

   • Type / 種類： Streamable HTTP（ない場合は SSE / HTTP）

   • URL / ドレス： http://<host-IP>:2222/mcp

     • 例：http://192.168.1.50:2222/mcp

     • 同じマシンの場合：http://localhost:2222/mcp

5. 保存し、サーバーを有効化（Enable） します。Che Studio が ssh_test, ssh_execute, ssh_upload, ssh_download ツールを読み込みます。

リモートマシンから接続する場合は、2222 ポートが到達可能であること（ファイアウォールで許可）、Docker が 0.0.0.0 で待ち受けること（初期状態でそうなっています）を確認してください。

B) stdio モード

Cherry Studio が stdio 形式の MCP サーバー（コマンド起動）を期待する場合：

• Command： docker

• Arguments：

  exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

（この場合、ssh-mcp-server コンテナが実行中である必要があります — docker compose up -d。）

5. .env 構成

Docker でのキー認証

キーをコンテナにマウントし、パスを設定します。docker-compose.yml で volumes 行のコメントを解除します：

    volumes:
      - ./keys:/keys:ro

そして .env に設定します：

SSH_PRIVATE_KEY_PATH=/keys/id_ed25519

6. テスト用 REST エンド ポイント（OpenAPI）

HTTP モードは、Cherry Studio 用の MCP エンドポイントに加えて REST エンドポイントも提供します。これらは同じ SSH 操作を実行でき、curl / Swagger UI から簡単に利用できます：

例（一括単一コマンド実行）：

curl -X POST http://localhost:2222/api/ssh/execute \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret","command":"uname -a"}'

セキュリティ上の注意

• 秘密はコード内に決して含めない — すべて .env または呼び出しパラメータから読み取ります。

• .env ファイルは .dockerignore と通常は .gitignore によっても除外されます — バージョン管理にコミットしないでください。

• サーバーは AutoAddPolicy を使用します (未知のホストキーの自動受け付け)。 閉域ネットワークでは安全ですが、より厳しい環境では、既知のホストキーを使用することをお勧めします。

• 2222 の MCP ポートは、信頼できるネットワークでのみ公開してください。