gcv-kie-mcp

MCP-сервер для kie.ai: 12 инструментов для генерации изображений, видео и музыки с оценкой стоимости до запуска и лимитами расхода.

claude mcp add gcv-kie -s user -e KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp

Требуется Node ≥ 20. Работает с любым MCP-клиентом: Claude Code, Claude Desktop, Codex, Cursor, Antigravity, Windsurf.

---

Зачем

Прямой доступ агента к платному API опасен: списание происходит в момент создания задачи, до того как станет ясно, что результат получится. Сервер закрывает это:

• Цены живые. Прайс запрашивается у kie.ai при обращении и не хранится на диске — устаревшая цена не может пережить перезапуск и тихо испортить смету
• Оценка до запуска. kie_estimate считает стоимость по этому прайсу. Цены нет — инструмент возвращает known: false, а не догадку
• Лимит на вызов. maxCostCredits отклоняет генерацию при превышении
• Защита от повтора. Одинаковый вызов в пределах суток не создаёт вторую задачу
• Журнал трат. kie_ledger показывает, что и сколько стоило

Описание kie_generate явно требует предварительных kie_catalog_show, kie_estimate и согласия пользователя на сумму — это видит модель, а не только человек в документации.

---

Инструменты

Инструмент	Что делает	Тратит деньги
kie_doctor	Ключ, связь, состояние каталога, курс	нет
kie_balance	Остаток на счету	нет
kie_catalog_list	Модели с ценами и лимитами	нет
kie_catalog_show	Карточка модели: схема input, лимиты, цена	нет
kie_catalog_refresh	Принудительно перечитать и цены, и схемы моделей	нет
kie_catalog_set	Записать модель вручную, если автоматика её не нашла	нет
kie_estimate	Оценка стоимости	нет
kie_generate	Создать генерацию и забрать результат	да
kie_status	Состояние задачи по taskId	нет
kie_wait	Дождаться завершения задачи	нет
kie_upload	Залить файл, получить URL для референса	нет
kie_ledger	Журнал трат	нет

---

Подключение

Claude Code

Все оболочки Claude Code читают общий конфиг — достаточно одной регистрации из любого терминала:

claude mcp add gcv-kie -s user -e KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp

-e передаёт ключ переменной окружения дочернего процесса: она не видна в списке процессов ОС. -s user — сервер доступен из любого проекта, -s local — только из текущего.

claude mcp get gcv-kie

Ожидается Status: ✔ Connected.

Claude Desktop

Расширение .mcpb — ключ вводится в форме при установке и хранится в системном хранилище учётных данных, а не в открытом файле. Готовый файл приложен к каждому релизу: скачать и открыть двойным кликом либо перетащить в окно приложения.

Собрать самому:

git clone https://github.com/extreez/MCP-KIE.git && cd MCP-KIE && npm run mcpb

Ручной JSON — в claude_desktop_config.json:

{
  "mcpServers": {
    "gcv-kie": {
      "command": "npx",
      "args": ["-y", "gcv-kie-mcp"],
      "env": { "KIE_API_KEY": "sk-your-key" }
    }
  }
}

Ключ здесь лежит открытым текстом — расширение безопаснее.

Codex

codex mcp add gcv-kie --env KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp

Либо в ~/.codex/config.toml:

[mcp_servers.gcv-kie]
command = "npx"
args = ["-y", "gcv-kie-mcp"]
env = { KIE_API_KEY = "sk-your-key" }

Проверка: codex mcp list, подробнее — codex mcp get gcv-kie.

Antigravity

Конфиг общий для IDE, CLI и SDK: ~/.gemini/config/mcp_config.json, в проекте — .agents/mcp_config.json. Через интерфейс: «…» над панелью агента → MCP Servers → Manage MCP Servers → View raw config.

{
  "mcpServers": {
    "gcv-kie": {
      "command": "npx",
      "args": ["-y", "gcv-kie-mcp"],
      "env": { "KIE_API_KEY": "sk-your-key" }
    }
  }
}

Cursor

~/.cursor/mcp.json глобально или .cursor/mcp.json в проекте — формат тот же.

Windsurf

~/.codeium/windsurf/mcp_config.json — формат тот же.

Другой клиент

JSON-RPC 2.0 через stdio, поддерживаемые версии протокола: 2025-06-18, 2025-03-26, 2024-11-05.

npx -y gcv-kie-mcp

Проверить без клиента:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y gcv-kie-mcp

---

Ключ доступа

Берётся на https://kie.ai/api-key

Порядок поиска:

.env проекта → KIE_API_KEY → ~/.gcv/config.json → аргумент --api-key

Сервер не печатает значение ключа — только источник и маску (sk-1…9f2c).

Аргумент --api-key виден в списке процессов ОС. В конфигах клиентов используйте env.

---

Откуда берутся цены

Прайс запрашивается у kie.ai при обращении к каталогу и живёт только в памяти процесса. На диск он не попадает — поэтому смета не может быть построена по цене месячной давности.

Схемы моделей (поля input, лимиты, допустимые значения) кэшируются на 30 дней в ~/.gcv/cache/kie/specs.json. Они описывают устройство модели, а не деньги, и меняются примерно раз в релиз. Цен в этом файле нет.

Что это значит на практике:

Когда	Сколько ждать
Первое обращение после установки	около минуты — читаются схемы всех моделей
Первое обращение в новой сессии	около 5 секунд — только прайс
Последующие в той же сессии	мгновенно, прайс держится минуту

kie_catalog_refresh нужен редко: цены и так живые. Он полезен, когда появилась новая модель или её параметры выглядят неверно — тогда перечитываются и схемы.

Первый запуск

подбери модель для обложки и посчитай, сколько выйдет 3 варианта

Агент вызовет kie_catalog_list → kie_catalog_show → kie_estimate и покажет смету. kie_generate — только после подтверждения суммы.

Первый вызов займёт около минуты: читаются схемы моделей. Дальше быстро.

---

Цена-диапазон

У части моделей стоимость зависит от разрешения или наличия видео на входе. kie_estimate пытается свести диапазон к точному числу по тем же параметрам, что пойдут в генерацию:

Поле ответа	Смысл
priceBasis: "exact"	Цена сведена к одному числу
resolvedBy	По каким параметрам удалось сузить
missingFields	Какого параметра не хватает, чтобы сузить
isRange: true	Диапазон окончательный, сузить нечем

Лимит maxCostCredits и проверка баланса считают по верхней границе.

---

Файлы на диске

Путь	Что
~/.gcv/config.json	Конфиг, права 600
~/.gcv/cache/kie/specs.json	Схемы моделей, 30 дней. Цен здесь нет
~/.gcv/cache/kie/overrides.json	Модели, записанные через kie_catalog_set
~/.gcv/ledger.jsonl	Журнал трат, только дозапись
~/.gcv/idempotency.json	Защита от двойной оплаты: ключ → taskId
~/.gcv/output/	Результаты по умолчанию

Цены на диске не хранятся нигде.

Расположение переопределяется переменной GCV_HOME.

---

Доработка под себя

Пакет публикуется с исходниками, без сборки и минификации.

git clone https://github.com/extreez/MCP-KIE.git
cd MCP-KIE

Запустить свою копию, не устанавливая:

node mcp/server.mjs

Подключить свою копию в клиент — вместо npx -y gcv-kie-mcp укажите node /path/to/MCP-KIE/mcp/server.mjs.

Файл	За что отвечает
mcp/server.mjs	Протокол и описания инструментов
src/catalog.mjs	Живые цены, кэш схем. Только здесь, у CLI он другой
src/api.mjs	HTTP-вызовы kie.ai
src/registry.mjs	Разбор прайса, сведение цены к точной
src/generate.mjs	Preflight, оценка, запуск, опрос, скачивание
src/ledger.mjs	Журнал трат и защита от повтора
mcpb/build.mjs	Сборка расширения для Claude Desktop

Остальное содержимое src/ общее с CLI: логика одна, обёрток две. Источник правды — репозиторий CLI, здесь лежит копия, чтобы пакет ставился одной командой. Если правите ядро — правьте там, сюда переносите скриптом:

node sync-src.mjs --check

node sync-src.mjs --from ~/src/gcv-kie-cli

Скрипт намеренно не трогает catalog.mjs: у CLI он кэширует каталог на диске, здесь — тянет цены живьём. Правки в mcp/server.mjs и src/catalog.mjs — только здесь.

Добавили инструмент — добавьте его и в список tools в mcpb/build.mjs: этот список показывается в диалоге установки расширения до первого запуска сервера. CI сверяет оба списка.

Проверка после правок:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp/server.mjs

Issues и PR приветствуются. Требование к изменениям: kie_generate остаётся единственным инструментом, который тратит деньги, а лимиты не отключаются ради удобства.

---

Смежные инструменты

Инструмент	Назначение
gcv-kie	Те же операции из терминала, плюс pick, prices, schema, jobs, spend
gcv-creative	Скиллы для агента: пайплайн от брифа до галереи

CLI и MCP-сервер делят один каталог, конфиг и журнал трат — можно ставить оба.

---

MIT © Leonid Kamenik