gemini-media-mcp

Einheitlicher Go-MCP-Server für KI-Mediengenerierung über die Google Gemini API und Vertex AI.

Funktionen

• Bilderzeugung -- Text-zu-Bild mit konfigurierbaren Seitenverhältnissen und Auflösungen (1K/2K/4K)

• Bildbearbeitung -- Bestehende Bilder mit natürlichsprachlichen Prompts modifizieren

• Multi-Referenz-Komposition -- Kombinieren von bis zu 3 Referenzbildern mit Stil-/Inhaltsvorgaben

• Videoerzeugung -- Text-zu-Video über Veo 3.1 Lite, Fast und Standard-Tiers

• Bild-zu-Video -- Standbilder in Videoclips animieren

• Videoerweiterung -- Clips für längere Inhalte verketten (Fast- und Standard-Tiers)

• Text-zu-Sprache (TTS) -- Gesprochenes Audio mit konfigurierbaren Stimmen und Sprachen generieren

• Musikerzeugung -- KI-Musik über Lyria 3 (30-Sekunden-Clips oder vollständige Songs mit Gesang, Strukturkontrolle)

• Einzelne Binärdatei -- Keine Laufzeitabhängigkeiten, läuft über stdio-Transport

• Provider-Abstraktion -- Backend-agnostische Schnittstellen für Bild-, Video-, Audio- und Modelloperationen

• Dual-Backend -- Unterstützt sowohl Gemini API (API-Key) als auch Vertex AI (Projekt-Anmeldedaten)

Schnellstart

# 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

Fügen Sie es dann Ihrem MCP-Client hinzu -- siehe MCP-Client-Konfiguration unten.

Konfiguration

*Einer der Werte GOOGLE_API_KEY oder GOOGLE_CLOUD_PROJECT muss gesetzt sein. Wenn beide gesetzt sind, hat der API-Key Vorrang (vermeidet Konflikte, wenn GOOGLE_CLOUD_PROJECT in der Shell für andere Tools gesetzt ist).

Wenn Sie unsicher sind, welches Backend aktiv ist, rufen Sie get_config von Ihrem MCP-Client aus auf, um das ausgewählte Backend und das Ausgabeverzeichnis zu bestätigen.

Verfügbare Tools

Async-Tools geben sofort eine Operations-ID zurück. Verwenden Sie video_status, um den Abschluss abzufragen, und dann download_video, um die Datei abzurufen.

Modell-Tiers

Bild

Beide Tiers unterstützen Auflösungen von 1K, 2K, 4K und Seitenverhältnisse von 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

Video

Unterstützte Seitenverhältnisse sind 16:9 und 9:16. Unterstützte Dauern sind 4, 6 und 8 Sekunden. Lite unterstützt 720p und 1080p. Fast und Standard unterstützen 720p, 1080p und 4K. Videoerweiterung (extend_video) ist nur in den Fast- und Standard-Tiers verfügbar, und der Erweiterungs-Tier muss mit der ursprünglichen Generierung übereinstimmen.

Audio (TTS)

Das Tool generate_audio wandelt Text in gesprochenes Audio um. Es unterstützt:

• Stimmwahl -- Wählen Sie aus vorgefertigten Stimmen wie Aoede, Kore, Puck und mehr. Standard: Aoede

• Sprache -- Legen Sie den Sprachcode fest (z. B. en-US, it-IT, cs-CZ, de-DE). Standard: en-US

• Natürliche Sprache -- Generiert ausdrucksstarke, natürlich klingende Sprache mit angemessenem Tempo und Intonation

Die Ausgabe wird als rohes PCM-Audio (audio/L16, 24kHz Abtastrate) gespeichert. Die Datei kann mit Tools wie ffplay abgespielt oder in andere Formate konvertiert werden:

# 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

Musik (Lyria)

Das Tool generate_music erstellt KI-generierte Musik aus Textbeschreibungen. Zu den Fähigkeiten gehören:

• Genre und Stil -- Geben Sie Genre, Instrumente, BPM, Tonart/Skala, Stimmung an

• Strukturkontrolle -- Verwenden Sie Tags wie [Verse], [Chorus], [Bridge], [Intro], [Outro]

• Benutzerdefinierte Texte -- Fügen Sie Texte mit Abschnittsmarkierungen für Gesangsspuren hinzu

• Zeitstempelkontrolle -- [0:00 - 0:10] Intro: sanftes Klavier... für präzises Timing der Abschnitte

• Mehrsprachigkeit -- Die Prompt-Sprache bestimmt die Ausgabesprache

• Hohe Wiedergabetreue -- 48kHz Stereo MP3-Ausgabe

Alle generierte Musik ist mit SynthID mit einem Wasserzeichen versehen.

Beispiel-Prompts:

# 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"

Sie können den Tier-Namen (lite, fast, standard, nb2, pro, tts, clip, full) oder direkt eine rohe Modell-ID übergeben.

MCP-Client-Konfiguration

Claude Code

Fügen Sie dies zu Ihren Claude Code MCP-Einstellungen hinzu (~/.claude/settings.json oder Projekt .mcp.json):

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

Verwenden Sie entweder GOOGLE_API_KEY oder GEMINI_API_KEY im env-Block oben; beide werden akzeptiert.

Oder beim Bauen aus dem Quellcode:

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

Begleitende Skills für Claude Code

Das Verzeichnis skills/ enthält Claude Code-Skills, die interaktive Workflows zusätzlich zu den MCP-Tools bereitstellen. Jeder Skill führt Claude durch Prompt-Engineering, Modellauswahl und iterative Verfeinerung für einen bestimmten Medientyp.

Um einen Skill zu installieren, kopieren Sie dessen Verzeichnis nach ~/.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/

Skills sind optional — die MCP-Tools funktionieren auch ohne sie. Die Skills fügen jedoch Anleitungen zum Prompt-Engineering, Empfehlungen für Modell-Tiers und interaktive Review-Workflows hinzu, die die Ausgabequalität erheblich verbessern.

Bauen aus dem Quellcode

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

Die Binärdatei wird unter ./gemini-media-mcp erstellt.

Um Tests auszuführen:

go test ./...

Mitwirken

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/your-feature)

3. Nehmen Sie Ihre Änderungen vor und fügen Sie Tests hinzu

4. Führen Sie go test ./... und go vet ./... aus

5. Committen Sie Ihre Änderungen

6. Öffnen Sie einen Pull Request gegen main

Lizenz

Apache-2.0