ftp-deploy-mcp

AIコーディングエージェントのためのデプロイボタン。 Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → あなた自身のFTP / FTPS / SFTPサーバーへ。

Version française → README.fr.md

エージェントがデプロイを実行 — あなたは頼むだけ。

なぜ

• どのWebプロジェクトも最後は同じ結末を迎えます：「それをサーバーに上げて」。

• AIエージェントは優れたコードを書きますが、従来のホスティング（OVH、Ionos、Hostinger、o2switchなど、共有ホスティングの世界は今もFTP/SFTPで動いており、git pushではありません）に安全に配信する手段を持たないものがほとんどです。

• ftp-deploy-mcp は、あらゆるMCPクライアントに、コードが書かれたのと同じ会話の中で、あなた自身のインフラへのデプロイ経路を提供します。

• 汎用のSSH実行MCPサーバーとは異なり、これはファイルデプロイ専用に作られています：パス・ジェイル、読み取り専用モード、ドライラン、そしてモデルのコンテキストに決して入らない認証情報。

Related MCP server: mcp-remote-ssh

機能

クイックスタート

1. git clone https://github.com/alebgl77/ftp-deploy-mcp.git && cd ftp-deploy-mcp

2. install.cmd（ダブルクリック、Windows）または ./install.sh（macOS / Linux）を実行します。

3. IDEを再起動して、エージェントにこう頼みます："./dist を prod にデプロイして。"

仕組み

flowchart LR
subgraph agents [AI agents]
  A[Claude Code]; B[Cursor]; C[Windsurf]; D[Trae]; E[Antigravity]
end
agents -- MCP stdio --> S[ftp-deploy-mcp<br/>10 tools · path jail · read-only guard]
S -- FTP / FTPS --> F[(your web hosts)]
S -- SFTP --> G[(your servers)]
K[ftp-servers.json<br/>credentials stay local] -.-> S

1. これは何か

MCP（Model Context Protocol）サーバーであり、stdio上で動作し、コーディングエージェントに10個のツールを公開します。認証情報はローカルの設定ファイルに保存され、LLMのコンテキストを経由することは決してありません。すべてのリモート操作は、サーバーごとに選択したroot配下に制限されます。

Node.js >= 18 が必要です。コンパイルが必要なネイティブ依存関係はありません。

2. インストール

⚡ ワンコマンドインストール（推奨）

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp

次にウィザードを起動します：

• Windows: install.cmd をダブルクリック。

• macOS / Linux: ./install.sh（必要に応じて最初に chmod +x install.sh を実行）。

• または手動で: npm install && npm run setup。

setupウィザードがすべてを自動で行います：

• サーバー設定を作成またはインポートします（既存サイトのFileZillaインポートを含む）；

• 各サーバーへの接続をテストします；

• 検出されたMCPクライアント（Claude Code、Claude Desktop、Cursor、Windsurf、Antigravity）の設定ファイルを自動的に書き込みます — 既存ファイルを変更する前に**.backup-<date>**バックアップを作成します；

• Trae用の**貼り付け可能なブロックを表示（およびコピー）**します。TraeはUIから設定します。

次にIDEを再起動して、エージェントに例えば「FTPサーバーを一覧表示して」と頼みます。

診断とオプション

いつでも、読み取り専用の診断（何も書き込みません）を実行できます：

npm run doctor          # or: node src/index.js doctor

Nodeのバージョン、使用中の設定ファイル、サーバー一覧（パスワードは決して表示されません）、およびクライアントごとにftpエントリがこのインストールに配線されているかどうかを表示します。

setupオプション（node src/index.js setup [options]）：

(b) グローバルインストール

npm install -g .

ftp-deploy-mcpコマンドがPATHに追加されます。node .../src/index.jsの代わりにこれを使用します。

(c) npmへの公開（npx -yでの使用向け）

このパッケージを自分の名前でnpmに公開した場合、クライアントは事前インストールなしで実行できます：

{ "command": "npx", "args": ["-y", "your-package-name"] }

3. サーバー設定

ftp-servers.jsonファイルを作成します。サーバーは次の順序で探します（最初に見つかったものが優先）：

1. --config <path>（コマンドライン引数）

2. FTP_MCP_CONFIG環境変数（JSONへのパス）

3. ./ftp-servers.json（プロセスの作業ディレクトリ）

4. ~/.ftp-mcp/servers.json

完全なスキーマ

{
  "defaultServer": "prod",          // optional: used when "server" is not given
  "servers": {
    "prod": {
      "protocol": "sftp",           // REQUIRED: "ftp" | "ftps" | "sftp"
      "host": "ssh.example.com",    // REQUIRED
      "port": 22,                    // optional (defaults: ftp/ftps 21, implicit ftps 990, sftp 22)
      "user": "deploy",             // REQUIRED
      "password": "${ENV:PROD_PW}", // optional: password (or an env placeholder)
      "privateKeyPath": "~/.ssh/id_ed25519", // optional (sftp); "~" is expanded
      "passphrase": "…",            // optional: private-key passphrase
      "root": "/var/www/site",      // optional (default "/"): ALL ops are jailed under it
      "readOnly": false,             // optional: blocks upload/deploy/mkdir/rename/delete
      "insecureTLS": false,           // optional (ftps): skip certificate checks — requires "allowInsecure"
      "implicitTLS": false,          // optional (ftps): implicit TLS (port 990, legacy servers)
      "allowInsecure": false         // optional: explicit opt-in REQUIRED for plain "ftp" or "insecureTLS"
    }
  }
}

上記のブロックは説明用に//コメントを使用しています。実際のファイルは厳密なJSON（コメントなし）でなければなりません。ftp-servers.example.jsonを参照してください。

環境変数の置換

任意の文字列値に${ENV:VARIABLE_NAME}を含めることができます。起動時に環境変数の値に置き換えられます。変数が未設定の場合、ツールは欠落している変数を明示した明確なエラーを返します。

"password": "${ENV:OVH_FTP_PASSWORD}"

セキュリティのヒント

• SFTPを推奨します。 平文のftpおよびinsecureTLS: trueのftpsはデフォルトで拒否されます：これらのトランスポートでは、ネットワーク攻撃者が認証情報やファイルを傍受または改ざんできます。どうしても使用する場合は、そのサーバーに明示的に"allowInsecure": trueを設定する必要があります — そうすると、起動ログとツール結果のすべてに、目に見えるセキュリティ警告が表示されます。

• ftp-servers.jsonを.gitignoreに追加します（このリポジトリではすでに実施済み）。

• ファイルのパーミッションを制限します（Unixではchmod 600 ftp-servers.json）。

• 平文パスワードよりも環境変数（${ENV:…}）またはSSHキーを推奨します。

• エージェントが絶対に書き込んではならないサーバーにはreadOnly: trueを使用します。

• rootは可能な限り狭く設定します：ジェイルは../による脱出を防ぎます。

4. FileZillaからのインポート

すでにFileZillaにサイトがありますか？変換します：

# Auto-detect the default sitemanager.xml location…
node src/index.js import-filezilla

# …or an explicit file, written to an ftp-servers.json
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json

--outを指定しない場合、JSONはstdoutに出力されます。Base64エンコードされたパスワードはデコードされます。保存されたパスワードがないサイトには${ENV:<NAME>_PASSWORD}プレースホルダーが設定されます（変数は自分で設定します）。出力例：

{
  "defaultServer": "my-site",
  "servers": {
    "my-site": {
      "protocol": "ftp",
      "host": "ftp.example.com",
      "user": "deploy",
      "password": "…",
      "root": "/www/html"
    }
  }
}

注意：生成されたファイルにはデコードされた平文パスワードが含まれています — バージョン管理（.gitignore）の対象外にし、パーミッションを制限してください（chmod 600）。

平文FTPサイト：インポートされた"protocol": "ftp"サーバー（上記の例のような）は、sftp/ftpsに切り替えるか、明示的に"allowInsecure": trueを設定するまで、接続時に拒否されます — インポートはそれぞれについて警告を表示します。セキュリティを参照してください。

5. 手動クライアント設定（setupを使用しない場合）

npm run setupはこれらのファイルを自動的に書き込みます（バックアップ付き）。このセクションは、すべてを手動で配線したい場合にのみ役立ちます。

/absolute/path/to/ftp-deploy-mcp/src/index.jsを実際のパスに置き換えます（Windowsではフォワードスラッシュ/も機能します）。パッケージをnpmに公開した場合は、"command": "node", "args": ["…/src/index.js"]を"command": "npx", "args": ["-y", "your-package-name"]に置き換えます。

以下のファイルの場所は、執筆時点でのデフォルトの場所です。これらの製品のUIは進化するため、必要に応じて公式ドキュメントを確認してください。

Claude Code

プロジェクトルートの.mcp.json：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

または1コマンドで：

claude mcp add ftp -- node /absolute/path/to/ftp-deploy-mcp/src/index.js

Claude Desktop

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Cursor

~/.cursor/mcp.json（グローバル）または.cursor/mcp.json（プロジェクト）：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Trae

Traeには安定した設定ファイルがありません — すべてUIで行います。AIチャットパネル → 設定/歯車 → MCP → 追加 → 手動設定、そして貼り付けます（これはsetupが表示してクリップボードにコピーするブロックです）：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Antigravity

バージョンによって、ファイルは次のいずれかです：

• ~/.gemini/antigravity/mcp_config.json

• バリアント: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

エージェントのMCPパネル（MCPサーバー管理）→ サーバー追加を使用して、同じ構造で設定することもできます。

6. 10個のツール

すべてのリモートパス（path、remote_pathなど）はサーバーのrootからの相対パスであり、POSIXスタイルを使用します。serverパラメータは常に省略可能です（解決方法は以下を参照）。

サーバーの解決方法: 明示的な server パラメータ → defaultServer → サーバーが1つだけの場合はそのサーバー → それ以外の場合は利用可能な名前を一覧表示したエラー。

ftp_deploy のデフォルト除外パターン: **/node_modules/**、**/.git/**、.env、.env.*、 *.log、.DS_Store、Thumbs.db、ftp-servers.json、**/.ftp-mcp/**（指定した exclude グロブは追加されます。include は一致するファイルのみに制限します）。スラッシュを含まないパターンは任意の深さで一致します（gitignore と同様）。ネストされた apps/api/.env も除外されます。

7. プロンプトの例

• "./dist を prod サーバーにデプロイして。"

• "ovh の /www の中身を一覧表示して。"

• "prod から .htaccess を取得して見せて。"

• "./build を /www にデプロイするドライランを実行して、何が送信されるか確認したい。"

• "prod で index.old.html を index.html に名前変更して。"

8. セキュリティ

• デフォルトで安全な転送: 平文の FTP と、証明書検証を無効にした FTPS（insecureTLS: true）は、サーバーエントリが明示的に "allowInsecure": true を設定しない限り拒否されます。許可された場合、起動時、ftp_list_servers、doctor、およびそのサーバーのすべてのツール結果にセキュリティ警告が表示されます。

• ルートジェイル: すべての操作は正規化された後、サーバーの root 内に収まるか検証されます。root が / の場合でも、脱出の試み（../…）は拒否されます。

• 読み取り専用: readOnly: true はすべての書き込み操作（アップロード、デプロイ、mkdir、名前変更、削除）をブロックします。読み取りは引き続き機能します。

• LLM に資格情報を渡さない: パスワード、パスフレーズ、キーはツール出力に決して返されません。

• テレメトリなし、自分自身のサーバー以外への外部接続なし。

• 呼び出しごとの接続: 各ツールは接続を開き、操作を実行し、閉じます。永続的なセッションはありません。

9. トラブルシューティング

• タイムアウト / 接続できない（FTP）: 通常はファイアウォールによってパッシブモードがブロックされています。サーバーのパッシブポートに到達可能であることを確認してください。

• SFTP キー認証: privateKeyPath（~ は展開されます）を設定し、キーが暗号化されている場合は passphrase も設定します。キーのパーミッションを確認してください。

• "INSECURE CONNECTION REFUSED": サーバーが平文の FTP、または証明書検証が無効な FTPS を使用しています。sftp（または有効な証明書を使用した ftps）に切り替えるか、— 傍受のリスクを完全に受け入れる場合にのみ — そのサーバーに "allowInsecure": true を設定してください。

• 自己署名 FTPS: insecureTLS: true は検証されていない証明書を受け入れます。これにより中間者攻撃の保護が無効になるため、"allowInsecure": true も必要となり、呼び出しのたびにセキュリティ警告が表示されます。有効な証明書をインストールすることを推奨します。

• インプリシット FTPS（ポート990）: AUTH TLS コマンドなしで最初のバイトから暗号化するレガシーサーバーの場合は、implicitTLS: true（ftps プロトコル）を設定します。

• "no server configured": 4つの場所のいずれにもファイルが見つかりませんでした。ftp-servers.json を作成するか、--config <path> / FTP_MCP_CONFIG=<path> を渡してください。

• setup 後にクライアントがツールを認識しない: IDE を完全に再起動し（プロジェクトだけでなくすべてのウィンドウを閉じる）、その後 npm run doctor で配線を確認してください。

• 設定が無効でもサーバーが起動する: これは意図的なものです（MCP クライアントは起動時に停止するサーバーを嫌います）。正確なエラーは起動時に stderr に出力され、すべてのツール呼び出しで返されます。

開発

npm test          # runs the full smoke test (local FTP + SFTP, no external network)
node src/index.js --version
node src/index.js --help

コントリビューション

コントリビューションを歓迎します — 開発環境のセットアップ、プロジェクトの原則、PR チェックリストについては CONTRIBUTING.md を参照してください。

セキュリティ

脆弱性を発見しましたか？ 公開の issue を開くのはおやめください — 非公開で報告する方法については SECURITY.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。