ftp-deploy-mcp

Кнопка деплоя для ИИ-агентов, пишущих код. Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → ваши собственные FTP / FTPS / SFTP-серверы.

Французская версия → README.fr.md

Ваш агент выполняет деплой — вам нужно только попросить.

Зачем

• Любой веб-проект в итоге упирается в одно: «теперь залей это на сервер».

• ИИ-агенты пишут отличный код, но у большинства из них нет безопасного способа доставить его на классический хостинг — OVH, Ionos, Hostinger, o2switch и весь остальной мир общего хостинга до сих пор работают на FTP/SFTP, а не на git push.

• ftp-deploy-mcp даёт любому MCP-клиенту путь для деплоя в вашу собственную инфраструктуру — в том же диалоге, где был написан код.

• В отличие от универсальных MCP-серверов, которые выполняют SSH-команды, этот специально создан для развёртывания файлов: изоляция путей (path jail), режим только для чтения, dry-run и учётные данные, которые никогда не попадают в контекст модели.

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 на прод».

Как это работает

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, который настраивается через его интерфейс.

Затем перезапустите IDE и попросите агента, например: «Список моих FTP-серверов».

Диагностика и опции

В любой момент доступна read-only диагностика (ничего не записывает):

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 и ftps с insecureTLS: true отклоняются по умолчанию: на этих транспортах сетевой злоумышленник может перехватить или изменить учётные данные и файлы. Чтобы всё же использовать такой транспорт, необходимо явно задать для сервера "allowInsecure": true — и тогда каждый лог запуска и результат работы инструментов будет содержать заметное предупреждение о безопасности.

• Добавьте ftp-servers.json в ваш .gitignore (в этом репозитории это уже сделано).

• Ограничьте права доступа к файлу (chmod 600 ftp-servers.json в Unix).

• Предпочитайте переменные окружения (${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"].

Расположения файлов ниже — стандартные на момент написания; интерфейсы этих продуктов развиваются, поэтому при необходимости сверяйтесь с их документацией.

Claude Code

.mcp.json в корне проекта:

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

Или одной командой:

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 нет стабильного конфигурационного файла — всё делается через его интерфейс. Панель ИИ-чата → Settings/шестерёнка → MCP → Add → Configure Manually, затем вставьте (это блок, который 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 → единственный сервер, если он только один → в противном случае ошибка со списком доступных имён.

Исключения по умолчанию для ftp_deploy: **/node_modules/**, **/.git/**, .env, .env.*, *.log, .DS_Store, Thumbs.db, ftp-servers.json, **/.ftp-mcp/** (ваши glob-шаблоны exclude добавляются; include ограничивает набор соответствующими файлами). Шаблоны без слеша совпадают на любой глубине (как в gitignore): вложенный apps/api/.env тоже исключается.

7. Примеры запросов

• «Развернуть ./dist на сервере prod.»

• «Показать, что находится в /www на ovh.»

• «Забрать .htaccess с prod и показать мне.»

• «Сделать пробный запуск развёртывания ./build в /www, чтобы я увидел, что будет отправлено.»

• «Переименовать index.old.html в index.html на prod.»

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): укажите implicitTLS: true (протокол ftps) для устаревших серверов, которые шифруют с первого байта, без команды AUTH TLS.

• «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

Участие в разработке

Вклад приветствуется — см. CONTRIBUTING.md с описанием настройки разработки, принципов проекта и чек-листа для pull request.

Безопасность

Нашли уязвимость? Пожалуйста, не открывайте публичный issue — см. SECURITY.md о том, как сообщить о ней конфиденциально.

Лицензия

MIT — см. LICENSE.