ftp-ssh-mcp

ftp-ssh-mcp

FTP、FTPS、SFTP、SSH 経由で単一のリモートホストを操作する MCP サーバーです。一般的な共有ホスティングプランやシンプルな VPS で利用できるようなホストを対象としており、クラウドプロバイダーの API は対象外です。ツールは、ファイル転送（一覧表示、アップロード、ダウンロード、mkdir、削除）、SSH 経由のシェル実行、SSH 経由でも実行する MySQL クエリラッパーの 3 つの機能クラスに分かれています。デフォルトで有効なのはファイル転送のみです。シェル実行とデータベースアクセスはどちらもオプトインであり、明示的に有効にするまで無効のままです。この 2 つは同程度に危険なものとして扱ってください。mysql_query は本番データベースで任意の SQL を実行し、シェルに抜け出すこともできるため、もう一方より安全というわけではありません。

インストール

npm で公開されており、npx で実行できます。クローンやビルドは不要です。Node 20 以降が必要です。Windows、macOS、Linux で動作します。

1. MCP クライアントに追加する

Windows では、以下の各クライアントに示す cmd /c 形式を使用してください。 多くのクライアントはシェルを介さずに command を直接起動しますが、Windows の npx はその方法では実行できない .cmd の shim です。そのため、通常は有用なエラーが表示されないままサーバーの起動に失敗します。Windows では例外的なケースではなく、常にこのルールに従ってください。

{
  "mcpServers": {
    "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] }
  }
}

{
  "mcpServers": {
    "remote": { "command": "cmd", "args": ["/c", "npx", "-y", "ftp-ssh-mcp@1"] }
  }
}

{
  "servers": {
    "remote": { "command": "npx", "args": ["-y", "ftp-ssh-mcp@1"] }
  }
}

[mcp_servers.remote]
command = "npx"
args = ["-y", "ftp-ssh-mcp@1"]

[mcp_servers.remote]
command = "cmd"
args = ["/c", "npx", "-y", "ftp-ssh-mcp@1"]

2. 接続先ホストを指定する

プロジェクトルートに .env ファイルを作成します。サーバーは作業ディレクトリからこのファイルを読み込みます。プロジェクトスコープのクライアントでは、作業ディレクトリはプロジェクトルートです。

REMOTE_HOST=ftp.example.com
REMOTE_USER=deploy
REMOTE_PASSWORD=your-password
REMOTE_BASE_DIR=/home/deploy/public_html

これだけで、FTPS 経由の 6 つのファイルツールを利用できます。このファイルをバージョン管理に含めないでください。.env と .env.* を .gitignore に追加してください。サーバーが .env を読み込むのは、追跡対象の設定ファイルから認証情報を除外するためです。

クライアントにプロジェクトディレクトリがない場合（Claude Desktop）、または異なるアカウントに接続する複数のサーバーを利用する場合は、各サーバーに専用のファイルを指定してください。

{
  "mcpServers": {
    "prod": {
      "command": "npx",
      "args": ["-y", "ftp-ssh-mcp@1"],
      "env": { "MCP_ENV_FILE": "/absolute/path/to/.env.prod" }
    }
  }
}

シェル実行とデータベースアクセスを追加した、より詳細な設定例です。どちらもオプトインするまで無効です。

REMOTE_HOST=example.com
REMOTE_USER=deploy
REMOTE_PASSWORD=your-password
REMOTE_BASE_DIR=/home/deploy/public_html

# Pin the host key. Without this, any host key is accepted — see Security.
SSH_HOST_FINGERPRINT=SHA256:your-fingerprint-here
SSH_PORT=22
SSH_BASE_DIR=/home/deploy
SSH_ALLOW_EXEC=true
SSH_ALLOWED_CMDS=@basic,@node

# Runs the mysql client on the host over SSH. At least as dangerous as
# SSH_ALLOW_EXEC — read the Security section before enabling.
DB_USER=deploy_dbuser
DB_PASSWORD=your-db-password
DB_NAME=deploy_db

# Off by default; required for file_delete.
REMOTE_ALLOW_DELETE=true

すべての変数については .env.example を参照してください。各変数の役割については、以下の「設定」を参照してください。

3. 頼る前に確認する

npx -y ftp-ssh-mcp@1 --selftest

.env があるディレクトリから実行してください。設定を解決し、ツールを登録して1行の概要を出力します。接続は開かずに終了します。サーバーをクライアントに接続する前に、必要な機能が有効になったことを確認するために使用してください。

ftp-ssh-mcp 1.0.1 selftest OK. env=.env, transport=ftp, host=example.com,
capabilities=[files, ssh, mysql], tools=[file_list, file_upload, ...]

設定が不完全な場合、不足している変数名を示すメッセージを表示して、ゼロ以外のステータスで終了します。「トラブルシューティング」を参照してください。

オプション

--version と --help は設定を読み込む前に応答するため、まだ何も設定されていないマシンでも使用できます。どちらも stdout に出力します。サーバーが出力するそれ以外の内容は、stdout が JSON-RPC チャネルであるため stderr に出力されます。

--quiet は、DB_PASSWORD が設定されていない場合、ツールを登録しなかった MCP_CAPABILITIES の項目がある場合、ベースディレクトリが相対パスの場合の警告を抑制します。ただし、セキュリティ態勢が想定より弱いことを示す2つの警告、つまりホストキーが検証されていない場合と、パスの制限が無効になっている場合は、意図的に抑制しません。クライアントの設定ファイルで一度設定されたフラグは、二度と確認されません。そのため、修正するまで警告は表示され続けます。それこそが、抑制する価値のある唯一の状態です。

機能

機能のツールは、必要な変数が設定されてその機能が構成されており、かつ MCP_CAPABILITIES で対象が制限されている場合はそのリストに含まれているときにのみ登録されます。

files ツールは転送方式に依存しません。FILE_TRANSPORT で選択した転送方式（ftp または sftp）を使用し、両方のプロファイルが構成されていれば、各呼び出しでその呼び出しに限って転送方式を上書きできます。mysql_query はデータベースドライバーではなく、利便性のためのラッパーです。SSH 経由で SQL をホストにインストール済みの mysql クライアントに渡し（mysql --user=... --database=... --table を実行し、SQL は stdin から送信します）、その後 CLI のテーブル出力を解析します。接続プール機能やパラメーター化クエリのサポートはありません。多くの共有ホストでは、ホスト外からのデータベース接続が許可されないため、この機能が用意されています。クライアント側で実際のデータベース統合が必要な場合は、mysql_query ではなく、別の方法を使用してください。ssh_exec と同等の注意を払って有効にしてください。より軽く考えてはいけません。セキュリティを参照してください。

設定

すべての設定は、次の順序で環境変数から解決されます。まずプロファイル固有の変数（FTP_* または SSH_*）、次に共通の REMOTE_* フォールバック、最後に組み込みのデフォルト値が使われます。FTP と SSH の独立した 2 つのプロファイルがあり、どちらか一方、両方、またはいずれも単独で設定できます（ただし、起動には少なくとも 1 つが必要です）。

通常、変数はプロセス環境から読み込まれますが、設定の解決前にサーバーが現在の作業ディレクトリにある .env ファイルも読み込むため、認証情報を MCP クライアント自身の（追跡対象になっていることが多い）設定ファイルの外に置くことができます。すでに設定されている実際の環境変数は、.env ファイルより優先されます。別のファイルを指定するには MCP_ENV_FILE を使います。先頭の ~ はホームディレクトリに展開され、相対パスは作業ディレクトリを基準に解決されます。設定されているものの読み取り不可の場合は、.env に黙ってフォールバックして指定したものとは異なる認証情報を読み込むのではなく、起動に失敗します。.env パーサーはインラインコメントに対応していません。KEY=value # note は、 # note を含む = 以降のすべてを値として扱うため、コメントは別の行に記述してください。

シークレットの継承

シークレット以外の設定（HOST、USER、BASE_DIR）は、自由に REMOTE_* にフォールバックします。シークレット（PASSWORD、PRIVATE_KEY、PASSPHRASE）は、プロファイル固有の *_USER が設定されていない場合に限り、REMOTE_PASSWORD にフォールバックします。プロファイル固有のユーザー名を指定することは、別のユーザーとして接続することを意味します。そのユーザーに別アカウント用のパスワードを送ると、認証が繰り返し失敗します。多くの共有ホストでは、失敗が一定回数に達するとブルートフォース攻撃対策が作動し、ホスト側でアカウントがロックされます。FTP_USER（または SSH_USER）を設定する場合は、対応するパスワードも明示的に設定してください。

変数

コマンドプリセット

SSH_ALLOWED_CMDS のうち @ で始まる項目は、名前付きグループに展開されます。プリセットとコマンド名を自由に組み合わせられます（SSH_ALLOWED_CMDS=@basic,@php,rsync）。不明なプリセット名があると、起動に失敗します。プリセット名はホスティング製品ではなくスタックにちなんでおり、次のように展開されます。

解決可能な DB_PASSWORD が設定されていない DB_USER は、エラーとして扱われません。リモートの mysql クライアントは、接続時にパスワードを渡さず、~/.my.cnf や信頼されたローカルソケットから認証情報を取得する場合があるためです。サーバーは起動時に stderr に警告を出しますが、実行を拒否することはありません。クエリで認証に失敗した場合は、mysql_query のエラーメッセージに再び DB_PASSWORD が示されるため、起動時のログを見ていなくても MCP クライアント内で原因を確認できます。

チルダのベースディレクトリ

~ と ~/<dir> は受け付けられ、files ツールでは、アカウント自身のログインディレクトリに展開されます。SFTP では realpath(".")、FTP では PWD を使います。この取得処理は接続時に行われ、展開する ~ がある場合に限られるため、絶対パスのベースディレクトリには余計な処理がかからず、サーバーは起動時にネットワーク接続を必要としません。

ssh_exec と mysql_query では、同じ設定を別の方法で解決します。未加工の ~ をリモートのログインシェルに渡し、各コマンドの実行時にシェル自身が $HOME を展開するため、この経路では接続時の取得処理はありません。どちらの方法も、同じログインアカウントを基準に解決するため、実際には同じ結果になります。展開のタイミングと方法だけが異なります。

各プロファイルは、それぞれのログインディレクトリを基準に自身の値を展開します。これは意図的な設計です。多くの共有ホストでは FTP アカウントが chroot されているため、FTP の ~ は / ですが、SSH では実際の /home/<user> が見えます。そのため、REMOTE_BASE_DIR を通じて共有された ~/public_html は、どちらでも適切な場所に解決されます。

名前付きのホームディレクトリである ~other/site は、起動時に拒否されます。ただし、これは files ツールが登録されている場合に限ります（たとえば MCP_CAPABILITIES=ssh のようにそれらを除外した設定は正常に起動し、ssh_exec または mysql_query が初めてそこで cd を実行しようとしたときにのみ失敗します）。特定できるのはログインしたアカウントだけなので、名前付きのホームディレクトリはリテラルパスとしてサーバーに送られます。この場合は絶対パスを使用してください。

セキュリティ

• ssh_exec は、SSH_ALLOWED_CMDS に指定されたプログラム名のみを実行します。この名前は、コマンドの空白区切りの先頭トークンと照合されます。引数に対するポリシーではありません。

• この照合の前に、コマンドにシェルのメタ文字クラス（14文字：; & | $ ( ) { } < > \ および改行／復帰改行）のいずれかが含まれている場合、コマンドはそのまま拒否されます。そのため、呼び出しは常に単一の単純なコマンドに限られ、コマンドの連結、リダイレクト、置換はできません。

• files ツールに渡されるリモートパスと、SSH_BASE_DIR／FTP_BASE_DIR は解決され、プロファイルに設定されたベースディレクトリ内に制限されます。.. セグメントはそのまま拒否されます。制限はプロファイルごとに適用され、呼び出しごとの transport オーバーライドは、デフォルトのプロファイルではなく、選択したプロファイルの範囲内に制限されます。ベースディレクトリがまったく設定されていないプロファイルは制限されません。制限対象がないためです。そのため、各プロファイルは独自のベースディレクトリがない場合、もう一方のプロファイルのベースディレクトリを使用します。それでもベースディレクトリが設定されないトランスポートがある場合、サーバーは起動時に stderr に警告を出します。

• 削除（REMOTE_ALLOW_DELETE）とシェル実行（SSH_ALLOW_EXEC）はいずれもデフォルトで無効になっており、明示的に有効にする必要があります。

• SSH_HOST_FINGERPRINT で SSH ホストキーを固定してください。 設定しない場合、SSH と SFTP の接続では提示されたホストキーがそのまま受け入れられます。代わりに参照する known_hosts はないため、ネットワーク経路上の第三者が独自のキーを提示し、アカウントのパスワードを受け取る可能性があります。この変数を設定すると、キーが一致しない場合は、期待されるフィンガープリントと受信したフィンガープリントの両方を示すエラーで接続が中断されます。設定されていない場合、サーバーは起動時に stderr に警告を出します。信頼できるホストから次のコマンドで値を取得してください。

  ssh-keyscan -t rsa your-host.example.com | ssh-keygen -lf -
  

  SHA256:… フィールドをコピーしてください（16進数のダイジェストのみでも使用できます）。解析できないフィンガープリントは、「検証なし」へ黙ってフォールバックするのではなく、起動エラーになります。

• mysql_query は SQL からシェル文字列を組み立てません。クエリは mysql クライアントの標準入力に書き込まれるため、コマンドラインに展開されることはありません。

• DB_PASSWORD がホストのプロセス一覧に表示されることはありません。 コマンドの標準入力の先頭行として渡され、リモートシェルが MYSQL_PWD に読み込んで mysql プロセスにエクスポートします。そのため、どの argv にも含まれず、ps aux に表示されるのは無害なコマンドテキストのみです。シークレットが存在するのはプロセス環境内だけで、読み取り可能なのは所有者に限られます。この受け渡し方法には制約があり、改行を含むパスワードは明示的なエラーで拒否されます。DB_PASSWORD が未設定の場合、パスワードの仕組みは一切実行されないため、~/.my.cnf などホスト側の認証情報が実際に使用されます。

• mysql_query の権限は ssh_exec 以上であり、より制限されたものではありません。 本番データベースに対して任意の SQL を実行でき、mysql クライアントの \! コマンドはシェルエスケープとしてパイプ入力でも有効です。そのため、SSH_ALLOW_EXEC と SSH_ALLOWED_CMDS の設定に関係なく、\! curl … | sh でシェルが実行されます。この2つの機能は別々の機能なので、別々のスイッチで制御されています。一方がより安全だからではありません。mysql も ssh と同じ慎重さで有効にしてください。

以上の設定は、リモートホストをサンドボックス化するものではありません。許可されたコマンドは、設定されたアカウントの全権限で実行されます。また、ssh_exec で可能な操作と、そのアカウントで直接ログインした場合に可能な操作との間に隔離はありません。ガードが制限するのは、単一の呼び出しの形式（プログラム1つ、シェルの細工なし、ベースディレクトリ内にとどまるパス）であり、許可されたプログラム自体が実行時にできることではありません。

セキュリティ上の問題を見つけましたか？ SECURITY.md を参照し、非公開で報告してください。

既知のアドバイザリ

npm install ftp-ssh-mcp を実行すると、現在、@modelcontextprotocol/sdk の依存関係として間接的に取り込まれる @hono/node-server に関する中程度のアドバイザリが2件報告されます。Windows 上で、このパッケージの静的ファイルサーバーにパストラバーサルの問題があるという内容です。このサーバーは stdio 経由で JSON-RPC を通信し、HTTP リスナーを起動しないため、ここでは該当するコードパスに到達しません。また、npm が提示する唯一の「修正」は、SDK を互換性のないバージョンへダウングレードすることです。CI では npm audit --omit=dev --audit-level=high を実行しており、現時点では成功しつつ、重大度が高またはクリティカルな問題があればビルドを失敗させます。SDK が依存関係を更新すると、これらのアドバイザリは解消されます。

トラブルシューティング

まず、.env があるディレクトリから npx -y ftp-ssh-mcp@1 --selftest を実行してください。接続以外のサーバー起動時の処理をすべて再現するため、設定の問題とネットワークまたは認証情報の問題を切り分けられます。

開発

git clone https://github.com/Chris221/ftp-ssh-mcp.git
cd ftp-ssh-mcp
npm install
npm test
npm run selftest

npm test は、インプロセスの FTP サーバーを使用した機能登録テストとトランスポートテストを含む Vitest テストスイートを実行します。npm run selftest は環境変数（および存在する場合は .env）から設定を解決し、ツールを登録して、接続を開いたり stdio トランスポートを起動したりせずに、解決されたトランスポートと登録された機能を含む概要を 1 行で出力します。