# google-flow-mcp

MCP-сервер, который генерирует изображения и видео в [Google Flow](https://flow.google.com)
через браузер — на вашей подписке Google AI Pro, без ключей API и без оплаты за кредиты
сторонним сервисам.

Форк под macOS и русский интерфейс.

## Благодарность автору

Оригинал — **Gabriel Gargiulo**:

- страница в каталоге: https://lobehub.com/mcp/gabrielgargiulodev-google-flow-mcp
- исходники: https://github.com/GabrielGargiuloDev/google-flow-mcp

Тот, в свою очередь, вырос из [TMSSS05/google-flow-browser-mcp](https://github.com/TMSSS05/google-flow-browser-mcp).

Лицензия MIT сохранена вместе с копирайтом автора — см. [LICENSE](./LICENSE).
Здесь только правки под macOS и русский язык интерфейса, вся тяжёлая работа сделана им.

---

## ⚠️ Прочтите до установки

**Это неофициальная автоматизация браузера.** Официального API у Flow нет, сервер
управляет реальным окном Chrome, вошедшим в ваш аккаунт Google.

Из этого следует:

- Автоматизация сервисов Google **может нарушать условия использования** и создать риск
  для аккаунта. Решение — ваше и на ваш риск.
- Оригинальный проект дополнительно запускает Chrome с ключом, скрывающим признаки
  автоматизации. **В этом форке такого ключа нет** — ни в инструкции, ни в коде.
  Кому он нужен, смотрите README оригинала.
- Проект молодой: создан и последний раз обновлён в один день, один автор. Интерфейс
  Flow меняется, и селекторы будут ломаться. Это инструмент «пока работает», а не
  что-то, на что стоит завязывать процессы.

**Кредиты.** Изображения расходуют общий месячный пул почти незаметно, видео — заметно:
Veo 3.1 Lite ≈ 10, Fast ≈ 20, Quality ≈ 100, Omni Flash ≈ 15–30 из примерно 1000 в месяц.
Диалог подтверждения списания сервер принимает сам.

---

## Требования

| Что | Версия | Проверить |
|---|---|---|
| macOS | — | — |
| Node.js | ≥ 18 | `node -v` |
| Google Chrome | 149+ | `ls "/Applications/Google Chrome.app"` |
| Аккаунт Google | с доступом к Flow, лучше AI Pro | — |

## Установка

```bash
git clone https://github.com/mr-Abdrahimov/google-flow-mcp.git
cd google-flow-mcp
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
```

`PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` — не опечатка. Сервер подключается к вашему
системному Chrome через CDP, свои браузеры Playwright ему не нужны, а качать их
полгигабайта. Без флага установка займёт вчетверо больше места.

## Настройка

```bash
cp config/flow.config.example.json config/flow.config.json
```

Откройте `config/flow.config.json` и поправьте три поля:

```json
{
  "expectedAccount": "вы@gmail.com",
  "chromePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  "chromeUserDataDir": "/Users/ВЫ/.local/share/flow-chrome-profile",
  "cdpPort": 9222
}
```

- `expectedAccount` — сервер сверяет, что вошли под нужным аккаунтом, и откажется
  работать под чужим.
- `chromeUserDataDir` — **отдельный профиль**, не ваш повседневный. Сервер управляет
  этим окном: открывает вкладки, нажимает кнопки. Мешать его с рабочим браузером не надо.

Файл в `.gitignore` — почта и пути остаются у вас.

## Запуск Chrome

Сервер не поднимает браузер сам: он подключается к уже запущенному Chrome по протоколу
отладки. Запускать надо один раз за сеанс:

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.local/share/flow-chrome-profile" \
  --no-first-run \
  --no-default-browser-check \
  "https://flow.google.com/"
```

**При первом запуске** в открывшемся окне войдите в Google, а затем отдельно нажмите
«Sign in to Flow» — у Flow собственный вход. Сессия сохранится в этом профиле и дальше
будет подхватываться сама.

Проверить, что порт слушается:

```bash
curl -s http://127.0.0.1:9222/json/version
```

## Подключение к Claude Code

```bash
claude mcp add --scope user google-flow -- \
  "$(command -v node)" /абсолютный/путь/google-flow-mcp/src/index.js
```

Перезапустите Claude Code — MCP-серверы поднимаются при старте сессии, добавленный
на ходу не появится. Проверка: `claude mcp list`.

Для других клиентов:

```json
{
  "mcpServers": {
    "google-flow": {
      "type": "stdio",
      "command": "node",
      "args": ["/абсолютный/путь/google-flow-mcp/src/index.js"]
    }
  }
}
```

## Инструменты

**Подключение**

| Инструмент | Что делает |
|---|---|
| `flow_connect` | подключиться к Chrome, открыть Flow, сверить аккаунт |
| `flow_disconnect` | закрыть браузер и разорвать соединение |
| `flow_status` | состояние: браузер, страница, аккаунт, очередь задач |
| `flow_account_check` | проверить, что вошли под ожидаемым аккаунтом |
| `flow_queue_status` | очередь: активная задача, ожидающие, история |

**Генерация**

| Инструмент | Что делает |
|---|---|
| `flow_generate_image` | изображение по описанию |
| `flow_generate_video` | видео по описанию (расходует кредиты) |
| `flow_download_latest` | скачать последний результат |

**Персонажи и сцены**

| Инструмент | Что делает |
|---|---|
| `flow_create_character` | создать персонажа |
| `flow_import_character` | импортировать персонажа из JSON |
| `flow_open_characters` | открыть список персонажей |
| `flow_create_scene` | создать сцену |

**Прочее**

| Инструмент | Что делает |
|---|---|
| `flow_use_grid_architect` | Grid Architect: тема, кадры, движок, пропорции |
| `flow_open_tools_gallery` | галерея инструментов Flow |
| `flow_use_tool` | открыть любой инструмент по имени |
| `flow_discover_ui` | обойти страницы и собрать карту элементов |
| `flow_screenshot` | снимок текущей страницы |

## Модели и допустимые сочетания

Модель и длительность должны сочетаться, иначе агент Flow начнёт переспрашивать и
ничего не сгенерирует.

| Модель | Длительность | Пропорции |
|---|---|---|
| Veo 3.1 Lite | только 8 с (на плане Pro) | 16:9, 9:16 |
| Veo 3.1 Fast / Quality | 4–10 с | 16:9, 9:16 |
| Omni Flash | 4–10 с | 16:9, 9:16 |
| Nano Banana Pro / 2, Imagen 4 | изображения | 16:9, 4:3, 1:1, 3:4, 9:16 |

## Что изменено в этом форке

**Русский интерфейс.** Оригинал искал кнопки по тексту и знал только итальянский,
французский и английский. На русском интерфейсе не совпадал ни один селектор — сервер
не мог даже создать проект. Проверено на живой странице:

```
✔ Новый проект (русский)     совпадений: 1
· New project (английский)   совпадений: 0
· Nouveau projet (франц.)    совпадений: 0
```

Русские подписи добавлены в создание проекта, подтверждение диалога, переключение
режимов «Видео» и «Изображение», Grid Architect, персонажей, сцены и скачивание.
Подписи «Новый проект» и «ОК» сняты с реальной страницы; остальные поставлены по смыслу
и помечены в коде комментарием — их стоит уточнить по факту.

**macOS.** В оригинале запуск Chrome был только скриптом PowerShell. Здесь он описан
командой в README, пути к Chrome и профилю — в конфиге.

**Сообщение об ошибке** при ненайденной кнопке было только по-французски.

## Известные шероховатости

- Описания двух инструментов (`flow_generate_image`, `flow_generate_video`) достались
  от предыдущих форков на французском и итальянском.
- Конфиг и код ссылаются на старый адрес `labs.google/fx/tools/flow`; Flow переехал на
  `flow.google.com`. Старый адрес пока отвечает, но интерфейс с тех пор изменился.
- Сервер рассчитан на то, что Chrome уже запущен и вход выполнен. Если порт не слушается,
  инструменты вернут ошибку подключения.

## Лицензия

MIT, копирайт Gabriel Gargiulo — см. [LICENSE](./LICENSE).