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 и согласия пользователя на сумму — это видит модель, а не только человек в документации.

Related MCP server: kie-ai-mcp-server

Инструменты

Подключение

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. Они описывают устройство модели, а не деньги, и меняются примерно раз в релиз. Цен в этом файле нет.

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

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

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

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

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

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

Что модель принимает на вход

kie_catalog_show возвращает limits.inputFiles — полный список файловых входов модели, включая картинки:

"limits": {
  "refField": "reference_image_urls",
  "maxRefs": 4,
  "inputFiles": [
    { "name": "first_frame_url",      "kind": "image", "maxItems": 1, "role": "start-frame" },
    { "name": "last_frame_url",       "kind": "image", "maxItems": 1, "role": "end-frame" },
    { "name": "reference_image_urls", "kind": "image", "maxItems": 4, "role": "primary" }
  ]
}

refField — не отдельный ответ, а указатель на запись с role: "primary". modes на вопрос «что можно приложить» не отвечает: wan/2-7-image-to-video числится image-to-video, то есть моделью создания, и при этом принимает ролик для продолжения в first_clip_url.

Как класть файлы в kie_generate и kie_estimate:

Первые три покрывают главный вход каждого вида. Всё остальное — конечный кадр, маска, второй референс — адресуется через files по имени поля из inputFiles. Поля, которого у модели нет, отклоняется до создания задачи: kie.ai лишнее поле принимает, деньги списывает и файл игнорирует.

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

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

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

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

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

Расположение переопределяется переменной 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.

Остальное содержимое 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 остаётся единственным инструментом, который тратит деньги, а лимиты не отключаются ради удобства.

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

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

MIT © Leonid Kamenik