gemini-media-mcp

Унифицированный MCP-сервер на Go для генерации медиаконтента с помощью Google Gemini API и Vertex AI.

Возможности

• Генерация изображений — преобразование текста в изображение с настраиваемым соотношением сторон и разрешением (1K/2K/4K)

• Редактирование изображений — изменение существующих изображений с помощью текстовых запросов

• Композиция с несколькими референсами — объединение до 3 референсных изображений с учетом стиля/содержания

• Генерация видео — преобразование текста в видео с использованием уровней Veo 3.1 Lite, Fast и Standard

• Преобразование изображения в видео — анимация статичных изображений в видеоклипы

• Расширение видео — объединение клипов для создания более длинного контента (уровни Fast и Standard)

• Преобразование текста в речь (TTS) — генерация озвученного аудио с настраиваемыми голосами и языками

• Генерация музыки — ИИ-музыка через Lyria 3 (30-секундные клипы или полноценные песни с вокалом и контролем структуры)

• Единый бинарный файл — отсутствие зависимостей среды выполнения, работает через транспорт stdio

• Абстракция провайдера — независимые от бэкенда интерфейсы для операций с изображениями, видео, аудио и моделями

• Двойной бэкенд — поддержка как Gemini API (API-ключ), так и Vertex AI (учетные данные проекта)

Быстрый старт

# Install
go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest

# Configure (Gemini API; either variable name works)
export GEMINI_API_KEY="your-api-key"
# export GOOGLE_API_KEY="your-api-key"

# Or configure (Vertex AI)
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# Run directly (stdio transport)
gemini-media-mcp

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

Конфигурация

*Необходимо задать либо GOOGLE_API_KEY, либо GOOGLE_CLOUD_PROJECT. Если заданы оба, приоритет имеет API-ключ (это позволяет избежать конфликтов, когда GOOGLE_CLOUD_PROJECT задан в оболочке для других инструментов).

Если вы не уверены, какой бэкенд активен, вызовите get_config из вашего MCP-клиента, чтобы подтвердить выбранный бэкенд и директорию вывода.

Доступные инструменты

Асинхронные инструменты немедленно возвращают ID операции. Используйте video_status для опроса о завершении, а затем download_video для получения файла.

Уровни моделей

Изображения

Оба уровня поддерживают разрешения 1K, 2K, 4K и соотношения сторон 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

Видео

Поддерживаемые соотношения сторон: 16:9 и 9:16. Поддерживаемая длительность: 4, 6 и 8 секунд. Lite поддерживает 720p и 1080p. Fast и Standard поддерживают 720p, 1080p и 4K. Расширение видео (extend_video) доступно только на уровнях Fast и Standard, при этом уровень расширения должен совпадать с исходной генерацией.

Аудио (TTS)

Инструмент generate_audio преобразует текст в озвученное аудио. Он поддерживает:

• Выбор голоса — Выбирайте из предустановленных голосов, таких как Aoede, Kore, Puck и других. По умолчанию: Aoede

• Язык — Установите код языка (например, en-US, it-IT, cs-CZ, de-DE). По умолчанию: en-US

• Естественная речь — Генерирует выразительную, естественно звучащую речь с соответствующим темпом и интонацией

Вывод сохраняется как необработанное PCM-аудио (audio/L16, частота дискретизации 24 кГц). Файл можно воспроизвести с помощью таких инструментов, как ffplay, или конвертировать в другие форматы:

# Play directly
ffplay -f s16le -ar 24000 -ac 1 ~/generated_media/audio-2026-04-02T12-20-12-0603.pcm

# Convert to WAV
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.wav

# Convert to MP3
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.mp3

Музыка (Lyria)

Инструмент generate_music создает ИИ-музыку по текстовым описаниям. Возможности включают:

• Жанр и стиль — укажите любой жанр, инструменты, BPM, тональность/гамму, настроение

• Контроль структуры — используйте теги, такие как [Verse], [Chorus], [Bridge], [Intro], [Outro]

• Пользовательские тексты — включите текст песни с маркерами секций для вокальных треков

• Контроль временных меток — [0:00 - 0:10] Intro: gentle piano... для точного тайминга секций

• Мультиязычность — язык запроса определяет язык вывода

• Высокая точность — вывод в формате 48 кГц стерео MP3

Вся сгенерированная музыка снабжена водяным знаком SynthID.

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

# Instrumental
"A gentle acoustic guitar melody in C major, 90 BPM, calm and peaceful indie folk"

# With structure
"[Intro] Ambient synth pad, ethereal
[Verse] Lo-fi hip-hop beat, mellow piano chords, vinyl crackle
[Chorus] Uplifting, add strings and gentle drums
[Outro] Fade out with reverb"

# With lyrics
"Upbeat pop song, 120 BPM, major key
[Chorus] We're dancing in the light / Everything feels right / Under stars so bright tonight"

Вы можете передать имя уровня (lite, fast, standard, nb2, pro, tts, clip, full) или непосредственно ID модели.

Конфигурация MCP-клиента

Claude Code

Добавьте в настройки MCP Claude Code (~/.claude/settings.json или проектный .mcp.json):

{
  "mcpServers": {
    "gemini-media": {
      "command": "gemini-media-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "MEDIA_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

Используйте либо GOOGLE_API_KEY, либо GEMINI_API_KEY в блоке env выше; принимаются оба варианта.

Или, если собираете из исходного кода:

{
  "mcpServers": {
    "gemini-media": {
      "command": "/path/to/gemini-media-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-api-key"
      }
    }
  }
}

Сопутствующие навыки для Claude Code

Директория skills/ содержит навыки Claude Code, которые предоставляют интерактивные рабочие процессы поверх инструментов MCP. Каждый навык направляет Claude через проектирование промптов, выбор модели и итеративное уточнение для конкретного типа медиа.

Чтобы установить навык, скопируйте его директорию в ~/.claude/skills/:

cp -r skills/video-gen ~/.claude/skills/
cp -r skills/music-gen ~/.claude/skills/
cp -r skills/tts-gen ~/.claude/skills/
cp -r skills/gemini-image-gen ~/.claude/skills/

Навыки необязательны — инструменты MCP работают и без них. Но навыки добавляют руководство по проектированию промптов, рекомендации по уровням моделей и интерактивные рабочие процессы проверки, которые значительно улучшают качество вывода.

Сборка из исходного кода

git clone https://github.com/mordor-forge/gemini-media-mcp.git
cd gemini-media-mcp
go build ./cmd/gemini-media-mcp/

Бинарный файл будет создан в ./gemini-media-mcp.

Для запуска тестов:

go test ./...

Вклад в проект

1. Сделайте форк репозитория

2. Создайте ветку для функции (git checkout -b feature/your-feature)

3. Внесите изменения и добавьте тесты

4. Запустите go test ./... и go vet ./...

5. Закоммитьте изменения

6. Откройте pull request в ветку main

Лицензия

Apache-2.0