Gemini Media

gemini-media-mcp

Google の生成メディアモデル向け MCP サーバーです。画像（Nano Banana 2.1 / Pro）、動画（Veo 3.1 と Gemini Omni Flash）、音声（Gemini 3.8 TTS）、音楽（Lyria 3.5）に対応しています。単一の Go バイナリとして提供され、stdio と Streamable HTTP（MCP 2026-07-28）を使用し、Gemini API または Vertex AIで動作します。また、ワークフロー全体をエージェントに教えるエージェントスキルに加え、Claude Code、Codex、Gemini CLI、VS Code/Copilot、Cursor など向けのプラグインパッケージも備えています。

https://github.com/user-attachments/assets/f46970b3-82a6-4364-a40a-922103dbbc70

エージェントが一度に 1 つのツールを使ってサーバーを利用する様子です。画像の生成と編集、動画クリップとそのクレイアニメ風への変換、768 px のポートレートをタイル状に分割して最大 8K に拡大した画像、さらに延長したショットを作成します。映像、ナレーション、音楽はすべてこのサーバーで生成されています。

• 最新モデルをリリースなしで更新。 組み込みカタログに ID、別名、ライフサイクル、パラメーター、価格が記録されています。廃止されたモデルは後継モデルにリダイレクトされ、カタログに登録される前の新しいモデル ID も使用できます。ホットリロードに対応した YAML ファイルで、カタログを上書きまたは拡張できます。
• コストを考慮。 すべての結果に推定コストが表示され、estimate_cost で支出前に選択肢を比較できます。支出は台帳に記録され、セッション、日次、月次の予算で上限が設定されます。また、しきい値を超える呼び出しには明示的な承認が必要です。
• エージェントに使いやすい設計。 各ツールがワークフローに対応し、エラーは [kind] message + Hint の形式で返されます。画像の結果にはインラインプレビューが含まれ、出力は URI を使って連鎖できます。動画は非同期ジョブとして実行され、ロングポーリングと進行状況通知に対応します。
• スキルを同梱。 6 つのエージェントスキルで、各メディア、複数アセットの制作、4K を超えるアップスケーリングを扱えます。アップスケーリングスキルでは、写真をタイルごとに再レンダリングし、タイルをつなぎ合わせて 8K 画像を作成します。
• 堅牢。 バックエンドと認証情報は Google SDK と同じ方法で検出されます。Vertex のロケーションはモデルごとに選択され、リトライとタイムアウトが組み込まれています。ファイルは出所情報とともにアトミックに書き込まれ、HTTP モードにはセキュリティのデフォルト設定が備わっています。

v0 からアップグレードしますか？ ツールが変更されています。移行表をご覧ください。レビューでは、何が壊れていたのか、その理由、v1 の設計についても説明しています。

クイックスタート

1. 認証情報を取得します。 次のいずれかを用意します。

   • Google AI Studio の API キー（GEMINI_API_KEY）、または
   • Vertex AI を有効にした Google Cloud プロジェクト（GOOGLE_CLOUD_PROJECT と gcloud auth application-default login）。

2. バイナリをインストールします。 macOS または Linux の場合：

   mkdir -p ~/.local/bin   # must be on your PATH
   os=$(uname -s | tr '[:upper:]' '[:lower:]'); arch=$(uname -m | sed 's/x86_64/x64/; s/aarch64/arm64/')
   curl -fsSL "https://github.com/mordor-forge/gemini-media-mcp/releases/latest/download/$os.$arch.gemini-media-mcp.tar.gz" \
     | tar -xz -C ~/.local/bin gemini-media-mcp
   gemini-media-mcp version
   

   Windows の場合は、最新リリースから windows の zip をダウンロードし、gemini-media-mcp.exe を PATH に追加します。Go 1.26 以降の場合：go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest。

   Gemini CLI 拡張機能、Claude Desktop バンドル、Docker イメージにはバイナリが含まれているため、この手順は不要です。

3. MCP サーバーをエージェントに追加します。 以下のすべての設定では、PATH から gemini-media-mcp を実行します。

   Claude Code（プラグイン：サーバーとスキル）、共有の mordor-forge マーケットプレイスから：

   /plugin marketplace add mordor-forge/claude-plugins
   /plugin install gemini-media@mordor-forge
   

   以前にこのリポジトリから mordor-forge を追加している場合は、まず /plugin marketplace remove mordor-forge を実行して切り替えてください。どちらの場合も、インストール済みのプラグインは引き続き動作します。 または、サーバーのみを追加します：claude mcp add gemini-media -e GEMINI_API_KEY=... -- gemini-media-mcp

   Codex（~/.codex/config.toml）：

   [mcp_servers.gemini-media]
   command = "gemini-media-mcp"
   env_vars = ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION"]
   tool_timeout_sec = 300   # 4K images and video polls can exceed the 60 s default
   

   Gemini CLI（2026 年 6 月以降、有料 API キー、Vertex AI、Gemini Code Assist のみ）：gemini extensions install https://github.com/mordor-forge/gemini-media-mcp

   Antigravity CLI： インストール設定例にあるように、サーバーを ~/.gemini/config/mcp_config.json に追加します。

   Claude Desktop： 最新リリースから gemini-media-mcp-<version>.mcpb をダウンロードして開きます。

   VS Code / Copilot： code --add-mcp '{"name":"gemini-media","command":"gemini-media-mcp"}'

   Cursor、Windsurf およびその他の mcpServers 形式のクライアント（Zed、OpenCode、Goose はそれぞれ独自の形式を使用します。以下を参照）：

   { "mcpServers": { "gemini-media": { "command": "gemini-media-mcp", "env": { "GEMINI_API_KEY": "..." } } } }
   

   デスクトップアプリで gemini-media-mcp が見つからないと表示される場合、シェルの PATH が参照されていません。command -v gemini-media-mcp でフルパスを確認して使用してください。すべてのクライアントに加え、Docker とスキルのインストーラーについても、packaging/INSTALL-SNIPPETS.mdで説明しています。

4. エージェントが環境変数を転送しない場合（プラグインではよくあります）、キーを一度だけ保存します。

   echo "$GEMINI_API_KEY" | gemini-media-mcp configure --api-key-stdin
   gemini-media-mcp doctor   # checks credentials, backend and model availability
   

代わりに Docker で実行する場合：docker run -i --rm --user "$(id -u):$(id -g)" -e GEMINI_API_KEY -v "$PWD/media:/output" -v gemini-media-state:/state ghcr.io/mordor-forge/gemini-media-mcp （--user を指定すると、Linux で生成されたファイルの所有者が自分になります。名前付きの /state ボリュームにより、利用料金の記録と動画ジョブが実行間で保持されます。）

ツール

ツール	機能
generate_image	最大14枚の参照画像を使ったテキストから画像への生成。1K～4K、多数のアスペクト比、1～4種類のバリエーションに対応し、Google Search によるグラウンディングも任意で利用できます
edit_image	既存の画像の一部を変更（追加／削除／スタイル変更／再照明／アウトペイント）し、それ以外は維持します
tile_image	任意の目標サイズ（1K～16K）へのアップスケールのステップ1：対象全体をカバーする最も低コストな切り抜きを計画し、編集モデルのアスペクト比に合わせて形状を調整します（約4Kまでは1タイル、それを超える場合はグリッド、または顔などの領域）。無料でローカルに実行されます
stitch_tiles	編集済みのタイルを画像に合わせて配置し、色を揃え、重なりをブレンドして、1枚の大きなPNGとして保存します（デフォルトは8K）。無料でローカルに実行されます
generate_video	テキスト、最初のフレーム、最初と最後のフレーム、または参照画像から、ネイティブ音声付きのクリップを生成します：Veo（4～8秒、最大3枚の参照画像）または Gemini Omni Flash（omni：3～10秒、360pのドラフトから4Kまで、最大10枚の参照画像）。jobId を返します
get_video	ジョブの完了を待ちます（ロングポーリング、デフォルト45秒）。完了すると動画をダウンロードします。安全に繰り返し実行できます
extend_video	完成したクリップを続けて生成します：Omni は最大10秒（合計40秒）、Veo は約7秒（合計最大148秒）を追加します
edit_video	Gemini Omni を使って、完成したクリップまたは最大10秒の動画ファイルを指示に従って変更します
generate_speech	テキスト読み上げ（WAV）：1人の音声、または2人の話者による会話を生成し、行ごとのスタイル制御と30種類の音声に対応します
generate_music	歌詞、構成タグ、テンポ、インストゥルメンタルモード、画像からのインスピレーションを指定して、30秒のクリップまたはフルサイズの曲を生成します
list_models	現在のモデル、エイリアス、ステータス、料金を表示します。detail で対応パラメーターを確認し、live で使用中のキーで利用できるかを確認できます
estimate_cost	リクエストの実行前に料金を見積もり、モデルを比較します
get_usage	期間、モデル、ツール別の推定費用、残りの予算、実行中のジョブを表示します
get_config	使用中のバックエンドと選択理由、出力ディレクトリ、デフォルト設定、警告を表示します

すべての結果には、保存したファイルのパス、gemini-media://files/<name> URI、料金が含まれます。この URI は別のツールへの入力として渡せます。サーバーのディスクを読み取れないクライアント（HTTP 経由など）は、resources/read を使って最大64 MBのファイルを取得できます（それより大きなアップスケール画像はサーバーのディスクに残ります）。

スキル

skills/ ディレクトリには、各メディアタイプのワークフロー全体（意図、プロンプトの作成、モデルの選択、コスト確認、レビュー、反復）をエージェントに教える Agent Skills が含まれています。対話形式での使用と、無人での実行の両方に対応しています。

スキル	用途
gemini-image	画像：生成、編集、複数の参照画像を使った合成、テキストの描画
gemini-video	動画：テキスト／画像からの動画生成、フレーム補間、参照素材、Omni による編集、延長、非同期ジョブ
gemini-speech	ボイスオーバー、ナレーション、2人の話者による会話、音声とスタイルの選択
gemini-music	構成、歌詞、テンポを指定したクリップやフルサイズの曲
gemini-media-production	複数のアセットを使ったプロジェクト（ストーリーボード → キーフレーム → 動画 → ボイスオーバー → 音楽 → ffmpeg による組み立て）と予算計画
gemini-upscale	写真を1K、2K、4K、8Kにアップスケールします：4Kまでは1タイル、それを超える場合は4Kタイルのグリッドをつなぎ合わせます。目の不一致などの欠陥を修正するパスも任意で利用できます。料金は1Kで約$0.04、8Kで約$0.50～1.20です。もっともらしいディテールを補完するもので、元のディテールを復元するわけではないため、フォレンジックやアーカイブ用途には適していません

プラグインをインストールすると（Claude Code、Codex、Gemini CLI、VS Code）、スキルも含まれます。Agent Skills 対応エージェントにインストールするには、npx skills add mordor-forge/gemini-media-mcp を実行するか、フォルダーを .agents/skills/ または ~/.claude/skills/ にコピーしてください。

モデル

エイリアスまたは完全なモデル ID を使用します。gemini-media-mcp models を実行すると、価格付きの組み込みカタログを確認できます。または list_models を呼び出してください。こちらはオーバーライドファイルも適用し、live: true を指定すると、お使いのキーで利用できるモデルも確認します。

メディア	エイリアス（デフォルトを先頭に表示）
画像	nb2（Nano Banana 2.1、デフォルト）、pro（Nano Banana Pro：最高の忠実度）、nb2-lite（入力が最も安価）
動画	omni（Gemini Omni Flash、Gemini API でのデフォルト：プロンプトへの忠実な対応、編集、最大 40 秒への延長。Gemini API 専用）、lite（最も安価な Veo、Vertex AI でのデフォルト）、fast（Veo 4K、参照画像、延長）、standard（最高品質の Veo）
音声	tts（Gemini 3.8 Flash TTS）、tts-lite、tts-2.5、tts-pro
音楽	clip（30 秒）、full（Lyria 3.5 の楽曲）

Gemini API での Veo。 Google は 2026-10-22 に、Gemini API での Veo 3.1 プレビュー（および gemini-omni-flash-preview モデル）の提供を終了します。それまでは lite、fast、standard を非推奨の警告付きで引き続き使用できます。終了後はサーバーが代わりに omni を使用し、その旨を通知します。Veo 3.1 は Vertex AI（現在の名称は Gemini Enterprise Agent Platform）で引き続き利用できます（veo-3.1-*-generate-001）。引き続き使用するには、Google Cloud プロジェクトを使ってサーバーを実行します。GOOGLE_CLOUD_PROJECT を設定し、gcloud auth application-default login を実行してください。API キーも設定している場合は GEMINI_MEDIA_BACKEND=vertex を指定します（Configuration を参照）。

リリースを待たずにモデルを更新または追加する。 YAML ファイルを作成し、GEMINI_MEDIA_CATALOG にそのファイルを指定します。サーバーは id を基準に組み込みカタログとマージし、自動的に再読み込みします。

defaults:
  video: fast
models:
  - id: veo-3.1-fast-generate-preview
    pricing: { perSecond: { 720p: 0.10, 1080p: 0.12, 4k: 0.30 } }
  - id: veo-4.0-generate-preview        # a brand-new model
    aliases: [veo4]
    pricing: { perSecond: { 720p: 0.50 } }

スキーマの全容については、internal/catalog/models.yaml を参照してください。

設定

設定は次の順に適用されます：組み込みのデフォルト値 < 設定ファイル < 環境変数 < フラグ。設定ファイルは、Linux では ~/.config/gemini-media-mcp/config.yaml、macOS では ~/Library/Application Support/gemini-media-mcp/config.yaml、Windows では %AppData%\gemini-media-mcp\config.yaml にあります。または、GEMINI_MEDIA_CONFIG が示す場所にあります。不明なキーがあってもエラーではなく警告が表示され、get_config では各設定の取得元を確認できます。

環境変数	設定キー	デフォルト	用途
GEMINI_API_KEY / GOOGLE_API_KEY / GEMINI_MEDIA_API_KEY	apiKey	–	Gemini API キー（または Vertex のエクスプレスモードキー）
GEMINI_MEDIA_PROJECT / GOOGLE_CLOUD_PROJECT	project	–	Vertex AI プロジェクト（アプリケーションのデフォルト認証情報）
GEMINI_MEDIA_LOCATION / GOOGLE_CLOUD_LOCATION / GOOGLE_CLOUD_REGION	location	モデルごと	Vertex のリージョン。そこで提供されていないモデルには、カタログのロケーションが使われます
GOOGLE_GENAI_USE_VERTEXAI / GOOGLE_GENAI_USE_ENTERPRISE	–	–	true は Vertex AI、false は Gemini API を選択します（Google SDK と同じ動作です）
GEMINI_MEDIA_BACKEND	backend	auto	auto、gemini-api、または vertex
MEDIA_OUTPUT_DIR / GEMINI_MEDIA_OUTPUT_DIR	outputDir	~/generated_media	メディアの保存先
GEMINI_MEDIA_STATE_DIR	stateDir	$XDG_STATE_HOME/gemini-media-mcp。未設定の場合は、Linux では ~/.local/state/gemini-media-mcp、それ以外では設定ディレクトリ	支出台帳と動画ジョブ
GEMINI_MEDIA_BUDGET_SESSION_USD / _DAILY_USD / _MONTHLY_USD	budget.*Usd	なし	支出上限（推定値）
GEMINI_MEDIA_CONFIRM_ABOVE_USD	budget.confirmAboveUsd	なし	この金額を超える呼び出しには approvedCostUsd が必要です
GEMINI_MEDIA_IMAGE_MODEL / _VIDEO_MODEL / _SPEECH_MODEL / _MUSIC_MODEL / GEMINI_MEDIA_VOICE	defaults.*	カタログ	デフォルトのモデルと音声（ここで設定したモデルは両方のバックエンドでデフォルトとして使われます。使用中のバックエンドで提供されていない場合、サーバーは起動を拒否します）
GEMINI_MEDIA_CATALOG	catalogFile	–	カタログの上書きファイル（ホットリロード対応）
GEMINI_MEDIA_INPUT_DIRS	inputDirs	–	入力を読み取れる追加ディレクトリ（HTTP モード）
GEMINI_MEDIA_ALLOW_ANY_INPUT_PATH	allowAnyInputPath	stdio では true、HTTP では false	ディスク上の任意の場所から入力ファイルを読み取るかどうか
GEMINI_MEDIA_INLINE_PREVIEWS / GEMINI_MEDIA_PREVIEW_MAX_PIXELS	inlinePreviews / previewMaxPixels	true / 768	画像の結果に縮小プレビューを添付するかどうか、およびプレビューの長辺のピクセル数
GEMINI_MEDIA_REQUEST_TIMEOUT_SECONDS	requestTimeoutSeconds	600	各 Google API リクエストのタイムアウト
GEMINI_MEDIA_MAX_VIDEO_WAIT_SECONDS	maxVideoWaitSeconds	600	動画ツールの waitSeconds の上限
GEMINI_MEDIA_RETRY_ATTEMPTS	retry.attempts	4	レート制限（429）および利用不可（503）の応答に対する試行回数
GEMINI_MEDIA_LOG_LEVEL	logLevel	info	debug、info、warn、または error（ログは stderr に出力されます）
GEMINI_MEDIA_TRANSPORT	transport	stdio	stdio または http
GEMINI_MEDIA_HTTP_ADDR / GEMINI_MEDIA_HTTP_TOKEN	http.addr / http.authToken	127.0.0.1:8765 / –	HTTP のリッスンアドレスとベアラートークン
–	http.path	/mcp	HTTP エンドポイントのパス
GEMINI_MEDIA_HTTP_ALLOWED_ORIGINS	http.allowedOrigins	–	追加で信頼するブラウザーのオリジン（カンマ区切り）
GEMINI_MEDIA_HTTP_STATEFUL	http.stateful	false	クライアントごとのセッションを維持するかどうか（セッションを必要とする旧式の 2025-11-25 クライアントのみ対象）

バックエンドの選択方法：

1. backend が明示的に設定されている場合は、その設定が優先されます。
2. そうでない場合は、SDK の GOOGLE_GENAI_USE_ENTERPRISE と GOOGLE_GENAI_USE_VERTEXAI の値で決まります。
3. それ以外の場合は、API キーがあると Gemini API が選択されます。ほかのツール用にシェルで GOOGLE_CLOUD_PROJECT を設定していても同様です。
4. それ以外の場合は、プロジェクトがあると Vertex AI が選択されます。

Vertex では、プロジェクトなしの API キーを使うとエクスプレスモードになり、動画はサポートされません。

支出と予算

Google は料金を返さないため、サーバーは料金表と API が報告するトークン使用量から料金を計算します。各呼び出しでは、実行前に見積もりを記録し、実行後に確定した料金を記録します。失敗した生成や安全性チェックでブロックされた生成の料金は $0 です。トークンを使用したもののメディアが返されなかった応答（たとえば MAX_TOKENS）には、そのトークン分の料金が発生します。

• 結果には cost {estimatedUsd, usd, basis} が含まれます。get_usage と gemini-media-mcp usage で支出を集計できます。台帳は状態ディレクトリ内の通常の JSONL ファイルです。
• 予算は各呼び出しの前に適用され、同時実行中の呼び出し間、および状態ディレクトリを共有する複数のサーバープロセス間で管理されます（実行中の呼び出しはファイルロックのもとで見積もり額を確保します）。
• GEMINI_MEDIA_CONFIRM_ABOVE_USD=1 を設定すると、高額な呼び出し（たとえば $3.20 の Veo クリップ）は [confirmation] エラーを返します。エージェントが確認を求めた後、approvedCostUsd を指定して再試行します。
• これらの数値は見積もりです。確実に支出を制限するには、AI Studio で支出上限を設定するか、Cloud Billing で予算を設定してください。

HTTP モード

GEMINI_API_KEY=... gemini-media-mcp serve --transport http                 # http://127.0.0.1:8765/mcp
GEMINI_MEDIA_HTTP_TOKEN=secret gemini-media-mcp serve --transport http --http-addr 0.0.0.0:8765
claude mcp add --transport http gemini-media http://127.0.0.1:8765/mcp --header "Authorization: Bearer secret"

• HTTP モードはステートレスな Streamable HTTP です。これは MCP 2026-07-28 が必須としており、古いクライアントでも引き続き動作します。
• サーバーは DNS リバインディングとクロスオリジンリクエストを防止します。
• トークンなしでは、ループバック以外のアドレスでのリッスンを拒否します。
• 入力ファイルは出力ディレクトリまたは GEMINI_MEDIA_INPUT_DIRS からのみ読み取ります（GEMINI_MEDIA_ALLOW_ANY_INPUT_PATH=true の場合を除く）。
• GET /healthz はステータスを報告します。

開発

有料のライブ E2E テストは、独自の API キーを使用してローカルで実行します。CI では無料の チェックを実行し、E2E テストのコンパイルと検査を行いますが、main へのマージ後や手動ワークフローの実行時も含め、ライブ生成は決して実行しません。

go build ./...
go test -race ./...
golangci-lint run
python3 scripts/validate-skills.py skills
GEMINI_MEDIA_E2E=1 GEMINI_API_KEY=... go test -tags=e2e ./internal/media/ -run E2E -v -timeout 30m   # live, costs cents
# add GEMINI_MEDIA_E2E_VIDEO=1 for the video test (~$0.20), GEMINI_MEDIA_E2E_OMNI=1 for the Omni clip + edit (~$0.30),
# GEMINI_MEDIA_E2E_UPSCALE=1 for a small tiled upscale (~$0.20),
# GEMINI_MEDIA_E2E_OUTPUT_DIR=./e2e-out to keep the files

• AGENTS.md：コーディングエージェントとコントリビューター向けのガイドです。
• docs/architecture-review.md：アーキテクチャと設計上の決定事項です。
• internal/catalog/models.yaml：モデルカタログです。Google がモデルを変更した場合は、コードではなくこのファイルを編集してください。

ライセンス

Apache-2.0