Grok Imagine Video MCP Server
This MCP server enables AI video generation, editing, extension, and asset upload through the xAI Grok Imagine Video API.
Generate videos from text (T2V), images (I2V), or reference images (R2V) with prompts, aspect ratios, resolution, and 1–15s duration.
Edit existing videos with prompts; output matches source duration (max 8.7s).
Extend existing videos by generating continuation segments (1–10s).
Upload local images/videos to xAI Files API for reusable file IDs.
Supports grok-imagine-video and grok-imagine-video-1.5 with model-specific limits, including 1080p and R2V voice presets on 1.5, while edit/extend are unsupported on 1.5.
Outputs MP4 with auto-generated AAC audio; supports async polling and cost reporting.
Includes a batch CLI for multiple jobs with concurrency, retries, cost estimates, and text/JSON output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grok Imagine Video MCP Server generate a 5-second video of a sunset over the ocean"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Grok Imagine Video MCP Server
xAI の Grok Imagine Video API 用 MCP (Model Context Protocol) サーバー。テキストプロンプトからの動画生成、画像からの動画生成(Image-to-Video)、既存動画の編集をサポートします。
クイックスタート (npx)
最も簡単な方法は npx を使用することです:
# APIキーを設定
export XAI_API_KEY="xai-your-api-key"
# サーバーを実行
npx grok-imagine-video-mcp-serverRelated MCP server: Google Veo 3.1 MCP Server
機能
動画生成(Text-to-Video): テキストプロンプトから新規動画を生成
動画生成(Image-to-Video): 画像を入力として動画を生成(プロンプト省略可)
動画生成(Reference-to-Video / R2V): 参照画像をスタイル/コンテンツ参照として動画を生成(
grok-imagine-video-1.5ではプリセットボイスreference_audiosも指定可)動画編集: 既存動画をプロンプトで編集
動画延長(Extension): 既存動画の続きを生成して延長
バッチ処理: CLIで複数動画を一括処理
多様なアスペクト比をサポート(16:9, 4:3, 1:1, 9:16 など)
解像度: 480p, 720p, 1080p(1080p は
grok-imagine-video-1.5限定)動画長: 1〜15秒(デフォルト8秒。編集時は元動画と同じ長さ、延長は2〜10秒)
音声つき(効果音・環境音・BGM が自動生成される。話者の声のみ 1.5 の
reference_audiosで選択可、それ以外はプロンプトで指示する)非同期処理対応(ポーリングによる結果取得、進捗・コスト表示)
grok-imagine-video 1.5 対応: Reference-to-Video(プリセットボイス含む)、動画延長、構造化エラー/進捗、実コスト(
cost_in_usd_ticks)表示に対応しています。
プロンプトの書き方は docs/prompt-templates.md を参照してください。
サポートモデル
モード |
|
|
Text-to-Video | ✅ | ✅ |
Image-to-Video | ✅ | ✅ |
Reference-to-Video | ✅ | ✅ |
R2V のプリセットボイス( | ❌ | ✅ |
編集 | ✅ | ❌ |
延長 | ✅ | ❌ |
1080p | ❌ | ✅ |
モデルと機能の対応について(2026-08-30 実機検証済み):
grok-imagine-video-1.5は Text-to-Video に続き Reference-to-Video も受け付けるようになりました(プリセットボイスreference_audiosを含む)。一方 編集・延長は引き続きVideo editing is not supported for this model./Video extension is not supported for this model.を返します。全モードを使えるのは基本モデルgrok-imagine-videoのみで、これがデフォルトです。なお 1080p が使えるのは T2V/I2V のみで、R2V の出力は 720p 上限です。1080p について: 1080p は
grok-imagine-video-1.5でのみ利用できます。公式ドキュメントは「1.5 の Image-to-Video 限定」と書いていますが、実測では 1.5 の Text-to-Video でも 1080p が通ります(出力実寸 1920x1088)。基本モデルで1080pを指定すると1080p video resolution is not available for this model.が返ります。これはアカウントの権限や Grok のサブスク(SuperGrok 等)とは無関係です。なお xAI の API 課金は消費者向け Grok サブスクとは別系統(前払いクレジット/請求)で、サブスク加入で API 機能が解放されることはありません。
音声
出力される MP4 には常に AAC 音声トラックが含まれます。効果音・環境音・BGM はプロンプトのシーン内容から自動生成されます。話者の声だけは grok-imagine-video-1.5 の R2V で reference_audios(プリセットボイス、最大3件。プロンプト中で <AUDIO_0> … と参照)として選択できますが、効果音・BGM を制御する API パラメータはありません。狙った音にしたい場合はプロンプト本文で指示します(テンプレート集参照)。音声が不要なら ffmpeg -i in.mp4 -c copy -an out.mp4 で除去してください。
必要条件
Node.js 22.23.4+ / 24.22.1+ / 26.12.1+(2026年10月のセキュリティリリース適用版)
xAI API キー(console.x.ai から取得)
インストール
方法1: npx(推奨)
npx grok-imagine-video-mcp-server方法2: グローバルインストール
npm install -g grok-imagine-video-mcp-server
grok-imagine-video-mcp-server設定
環境変数
変数 | 必須 | 説明 |
| Yes | xAI API キー |
| No |
|
| No | 動画のデフォルト出力ディレクトリ |
| No | ポーリング間隔(ミリ秒、デフォルト: 5000) |
| No | 最大ポーリング回数(デフォルト: 120) |
Claude Desktop 設定
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"grok-imagine-video": {
"command": "npx",
"args": ["-y", "grok-imagine-video-mcp-server"],
"env": {
"XAI_API_KEY": "xai-your-api-key-here"
}
}
}
}ツール
generate_video
テキストプロンプトまたは画像から動画を生成します。
パラメータ | 型 | 必須 | 説明 |
| string | 条件付き | 生成する動画の説明テキスト。T2V/R2V では必須、I2V(画像指定時)では省略可 |
| string | No | 出力ファイルパス(デフォルト: generated_video.mp4) |
| string | No | モデル(デフォルト: grok-imagine-video) |
| number | No | 動画長(1-15秒、デフォルト: 8) |
| string | No | アスペクト比(デフォルト: 16:9) |
| string | No | 解像度(480p/720p/1080p、デフォルト: 720p) |
| string | No | Image-to-Video用の入力画像URL |
| string | No | ローカル画像ファイルパス(base64 data URLとして送信。10MB超はFiles API経由で自動アップロード) |
| string | No | xAI Files API の File ID(Image-to-Video用) |
| array | No | Reference-to-Video用の参照画像(各要素は |
| array | No | R2V用のプリセットボイス(最大3件、各要素は |
注意:
image_url/image_path/image_file_idはいずれか1つのみ指定できます。また、画像(I2V)とreference_images/reference_audios(R2V)も同時指定できません。reference_audiosは単独指定(音声のみの R2V)も可能です。
edit_video
既存動画を編集します。
パラメータ | 型 | 必須 | 説明 |
| string | Yes | 編集内容の説明 |
| string | No* | 編集する動画のURL(公開アクセス可能、最大8.7秒) |
| string | No* | ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード) |
| string | No* | xAI Files API の File ID(*いずれか1つを指定) |
| string | No | 出力ファイルパス(デフォルト: edited_video.mp4) |
| string | No | モデル(デフォルト: grok-imagine-video) |
注意: 編集後の動画は元動画と同じ長さになります。
durationパラメータは編集時には指定できません。
extend_video
既存動画の続きを生成して延長します(grok-imagine-video 1.5)。
パラメータ | 型 | 必須 | 説明 |
| string | Yes | 続きで何が起こるかの説明 |
| string | No* | 延長する動画のURL(公開アクセス可能 or base64 data URL、.mp4) |
| string | No* | ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード) |
| string | No* | xAI Files API の File ID(*いずれか1つを指定) |
| string | No | 出力ファイルパス(デフォルト: extended_video.mp4) |
| string | No | モデル(デフォルト: grok-imagine-video) |
| number | No | 延長セグメントの長さ(2-10秒、デフォルト: 6) |
upload_file
ローカルの画像・動画ファイルを xAI Files API にアップロードし、file_id を取得します。ファイルは非公開のまま保存され、image_file_id / reference_images[].file_id / video_file_id として再利用できます(同じファイルを何度も送り直す必要がありません)。
パラメータ | 型 | 必須 | 説明 |
| string | Yes | アップロードするファイルのパス(画像: jpg/jpeg/png/gif/webp/bmp/tiff、動画: mp4、最大 48MB) |
バッチ処理 CLI
コマンド書式
grok-imagine-video-batch <config.json> [options]または npx 経由:
npx grok-imagine-video-batch <config.json> [options]基本的な使用例
# 設定ファイルでバッチ実行
npx grok-imagine-video-batch batch.json
# コスト見積もりのみ(実行しない)
npx grok-imagine-video-batch batch.json --estimate-only
# 出力先とフォーマットを指定
npx grok-imagine-video-batch batch.json --output-dir ./videos --format json
# ポーリング設定をカスタマイズ
npx grok-imagine-video-batch batch.json --poll-interval 10000 --max-poll-attempts 60
# 高並列実行(タイムアウト延長)
npx grok-imagine-video-batch batch.json --max-concurrent 5 --timeout 1800000
# ヘルプ表示
npx grok-imagine-video-batch --help
# バージョン表示
npx grok-imagine-video-batch --versionCLI オプション一覧
オプション | 短縮形 | 引数 | 説明 | デフォルト |
| - |
| 出力ディレクトリを上書き | 設定ファイルから |
| - |
| 出力フォーマット |
|
| - |
| タイムアウト(ミリ秒、最小1000) |
|
| - |
| 最大同時実行数(1-10) |
|
| - |
| ポーリング間隔(ミリ秒、最小1000) |
|
| - |
| 最大ポーリング回数 |
|
| - | - | コスト見積もりのみ(実行しない) | - |
| - | - | 任意の出力パスを許可(CI/CD用) | - |
|
| - | ヘルプメッセージ表示 | - |
|
| - | バージョン表示 | - |
終了コード
コード | 意味 |
| 成功(全ジョブ完了) |
| エラー(失敗またはキャンセルあり) |
バッチ設定ファイル
{
"jobs": [
{
"prompt": "猫がボールで遊んでいる",
"output_path": "cat_video.mp4",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
},
{
"prompt": "キャラクターが歩いているアニメーション",
"image_url": "https://example.com/character.jpg",
"output_path": "walking.mp4",
"duration": 10
},
{
"prompt": "ボールを大きくして",
"video_url": "https://example.com/video.mp4",
"output_path": "edited.mp4"
}
],
"output_dir": "./output",
"max_concurrent": 2,
"poll_interval": 5000,
"max_poll_attempts": 120,
"default_model": "grok-imagine-video",
"default_duration": 5,
"retry_policy": {
"max_retries": 2,
"retry_delay_ms": 1000
}
}ジョブ定義スキーマ
各ジョブは3種類のうち1つを指定します:
1. Text-to-Video(テキストから動画生成)
{
"prompt": "生成したい動画の説明",
"output_path": "output.mp4",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p",
"model": "grok-imagine-video"
}フィールド | 型 | 必須 | 説明 |
| string | Yes | 動画の説明テキスト |
| string | No | 出力ファイル名 |
| number | No | 動画長(1-15秒) |
| string | No | アスペクト比 |
| string | No | 解像度(720p/480p) |
| string | No | モデル名 |
2. Image-to-Video(画像から動画生成)
URL指定の場合:
{
"prompt": "画像をアニメーション化する説明",
"image_url": "https://example.com/image.jpg",
"output_path": "animated.mp4",
"duration": 5
}ローカルファイルの場合(base64 data URL):
{
"prompt": "画像をアニメーション化する説明",
"image_path": "./images/character.jpg",
"output_path": "animated.mp4",
"duration": 5
}フィールド | 型 | 必須 | 説明 |
| string | Yes | アニメーションの説明 |
| string | No* | 入力画像のURL(公開アクセス可能) |
| string | No* | ローカル画像ファイルパス(base64 data URLとして送信。10MB超はFiles API経由で自動アップロード) |
| string | No* | xAI Files API の File ID |
| string | No | 出力ファイル名 |
| number | No | 動画長(1-15秒) |
*
image_url/image_path/image_file_idのいずれか1つを指定(同時指定不可)
3. Reference-to-Video(参照画像から動画生成 / R2V)
{
"prompt": "アニメ風に歩くキャラクター",
"reference_images": [
{ "url": "https://example.com/style.jpg" },
{ "path": "./images/character.png" }
],
"output_path": "r2v.mp4",
"duration": 8
}フィールド | 型 | 必須 | 説明 |
| string | Yes | 動画の説明 |
| array | 条件付き | 参照画像(各要素は |
| array | 条件付き | プリセットボイス(最大3件、各要素は |
| string | No | 出力ファイル名 |
| number | No | 動画長(1-15秒) |
参照音声(プリセットボイス)を使う例:
{
"model": "grok-imagine-video-1.5",
"prompt": "<IMAGE_0> の人物が <AUDIO_0> の声で商品を紹介する",
"reference_images": [{ "path": "./images/person.png" }],
"reference_audios": [{ "voice_id": "eve" }],
"output_path": "r2v_voice.mp4",
"duration": 8
}画像(I2V)と
reference_images/reference_audios(R2V)は同時指定できません。reference_audios(プリセットボイス、最大3件)はgrok-imagine-video-1.5限定です。
4. Video Edit(動画編集)
{
"prompt": "編集内容の説明",
"video_url": "https://example.com/video.mp4",
"output_path": "edited.mp4"
}フィールド | 型 | 必須 | 説明 |
| string | Yes | 編集内容の説明 |
| string | No* | 編集する動画のURL(最大8.7秒) |
| string | No* | ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード) |
| string | No* | xAI Files API の File ID(*いずれか1つを指定) |
| string | No | 出力ファイル名 |
5. Video Extension(動画延長)
{
"operation": "extend",
"prompt": "カメラが引いて街並みが見える",
"video_url": "https://example.com/video.mp4",
"output_path": "extended.mp4",
"duration": 6
}フィールド | 型 | 必須 | 説明 |
| string | Yes |
|
| string | Yes | 続きで何が起こるかの説明 |
| string | No* | 延長する動画のURL |
| string | No* | ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード) |
| string | No* | xAI Files API の File ID(*いずれか1つを指定) |
| string | No | 出力ファイル名 |
| number | No | 延長セグメントの長さ(2-10秒、デフォルト6) |
video_url/video_path/video_file_idを持つジョブは既定で編集(edit)として扱われます。延長したい場合は"operation": "extend"を明示してください。
グローバル設定
フィールド | 型 | 説明 | デフォルト |
| string | 出力ディレクトリ |
|
| number | 最大同時実行数(1-10) |
|
| number | ポーリング間隔(ms) |
|
| number | 最大ポーリング回数 |
|
| string | デフォルトモデル |
|
| number | デフォルト動画長 |
|
| string | デフォルトアスペクト比 |
|
| string | デフォルト解像度 |
|
リトライポリシー
{
"retry_policy": {
"max_retries": 2,
"retry_delay_ms": 1000,
"retry_on_errors": ["rate_limit", "429", "500", "502", "503"]
}
}フィールド | 型 | 説明 | デフォルト |
| number | 最大リトライ回数 |
|
| number | リトライ間隔(ms) |
|
| string[] | リトライ対象エラー(エラーメッセージへの部分一致) |
|
service_unavailable と internal_error は xAI が「リトライすべき」と定義しているエラーコードです。
invalid_argument / permission_denied / failed_precondition はリクエスト内容の問題なのでリトライしません。
設定例は examples/ ディレクトリを参照してください:
batch-simple.json- 基本的な動画生成batch-image-to-video.json- 画像からの動画生成(URL指定)batch-local-images.json- ローカル画像からの動画生成batch-reference-to-video.json- 参照画像からの動画生成(R2V)batch-reference-voice.json- 参照画像+プリセットボイス/音声のみの R2V(grok-imagine-video-1.5)batch-with-edits.json- 動画編集チェーンbatch-extend.json- 動画延長(Extension)batch-social-media.json- SNS向けフォーマット
サポートされているアスペクト比
アスペクト比 | 用途例 |
| 横長ワイドスクリーン、YouTube(デフォルト) |
| 標準的な横長 |
| 正方形、Instagram |
| 縦長、TikTok、Reels、Stories |
| 縦長 |
| 写真比率 |
サポートされている解像度
解像度 | 説明 |
| フルHD画質( |
| HD画質(デフォルト) |
| 標準画質 |
動画長の制限
操作 | 最小 | 最大 | デフォルト |
生成(Text/Image/Reference-to-Video) | 1秒 | 15秒 | 8秒 |
編集 | - | 8.7秒 | 元動画と同じ |
延長(Extension) | 2秒 | 10秒 | 6秒 |
料金
動画 1 秒あたりの単価(USD)。1秒ジョブの usage.cost_in_usd_ticks から実測(2026-07-31)。
モデル | 480p | 720p | 1080p |
| $0.05 | $0.07 | 非対応 |
| $0.08 | $0.14 | $0.25 |
実課金額はジョブごとに
usage.cost_in_usd_ticksとして返り、結果表示に含まれますバッチ CLI の
--estimate-onlyはこの表で事前見積もりを出します(編集は 720p 単価で概算)参照画像・参照音声・入力画像・入力動画にも課金されるため、R2V の実額は上表の単価をやや上回ります(実測例: 1.5 / 480p / 1秒 / 参照画像1枚 + ボイス1件 = $0.09)
非同期処理について
Video APIは非同期で動作します:
リクエスト送信: 動画生成/編集リクエストを送信
request_id 取得: APIから
request_idが返されるポーリング: 定期的に結果を確認(デフォルト: 5秒間隔)
結果取得: 完了後、動画URLを取得してダウンロード
POST /v1/videos/generations → { request_id: "abc123" }
↓
GET /v1/videos/abc123 → { status: "pending" } → 待機
↓
GET /v1/videos/abc123 → { status: "completed", url: "..." } → ダウンロードstatus は pending / done(旧 completed) / failed / expired のいずれかです。
failed と expired は終端としてポーリングを打ち切り、エラーを返します(expired はリクエストの保持期限切れで、再送信が必要)。
使用例
# テキストから動画生成
「猫がボールで遊んでいる」の5秒動画を16:9で生成して
# 画像から動画生成
この画像のキャラクターを歩かせる動画を作って
# 動画編集
この動画の背景を夜に変更してAPI リファレンス
機能 | エンドポイント |
動画生成(T2V/I2V/R2V) |
|
動画編集 |
|
動画延長 |
|
結果取得 |
|
ドキュメント: docs.x.ai
開発
git clone https://github.com/ex-takashima/grok-imagine-video-mcp-server.git
cd grok-imagine-video-mcp-server
npm install
npm run build
npm start開発用コマンド
# ビルド
npm run build
# ウォッチモード
npm run dev
# バッチCLI実行
npm run batch -- examples/batch-simple.json --estimate-onlyトラブルシューティング
ポーリングがタイムアウトする
動画生成には時間がかかる場合があります。以下を試してください:
# ポーリング回数を増やす
npx grok-imagine-video-batch batch.json --max-poll-attempts 200
# タイムアウトを延長
npx grok-imagine-video-batch batch.json --timeout 1200000Rate Limit エラー
並列数を減らすか、リトライ設定を調整してください:
{
"max_concurrent": 1,
"retry_policy": {
"max_retries": 3,
"retry_delay_ms": 5000,
"retry_on_errors": ["rate_limit", "429"]
}
}関連プロジェクト
grok-imagine-image-mcp-server - 画像生成用MCP Server
ライセンス
MIT
作者
Junji Takashima takajyun00@gmail.com
Available Tools
4 toolsedit_videoA
Edit an existing video using xAI Grok Imagine Video API. Provide a source video URL along with a prompt describing the desired changes. The maximum supported video length is 8.7 seconds. The edited video will have the same duration as the original.
Inputs: prompt (required), model, video_url, video_path, +2 more.
extend_videoA
Extend an existing video by generating continuation content using xAI Grok Imagine Video API. Provide a source video URL and a prompt describing what should happen next. The extension segment duration is 1-10 seconds (default 6).
Inputs: prompt (required), model, duration, video_url, +3 more.
generate_videoA
Generate a new video using xAI Grok Imagine Video API (grok-imagine-video). Supports text-to-video (T2V), image-to-video (I2V), and reference-to-video (R2V). Supports aspect ratios: 16:9, 4:3, 1:1, 9:16, 3:4, 3:2, 2:3. Video duration: 1-15 seconds (default 8). Resolution: 480p, 720p, or 1080p (1080p only with model grok-imagine-video-1.5). The output MP4 always contains an auto-generated audio track (sound effects, ambience, score) driven by the prompt; there is no audio parameter. For image-to-video, provide image_url, image_path, or image_file_id. For reference-to-video, provide reference_images.
Inputs: model, prompt, duration, image_url, +6 more.
upload_fileA
Upload a local image or video file to the xAI Files API and get a file_id. The file stays private; the returned file_id can be used as input for generate_video (image_file_id, reference_images[].file_id), edit_video, and extend_video (video_file_id). Useful for reusing the same asset across multiple calls without re-uploading. Supported: images (jpg/jpeg/png/gif/webp/bmp/tiff) and videos (mp4), max 48 MB.
Inputs: file_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: generate creates new videos, edit modifies existing ones, extend continues them, and upload_file handles file ingestion. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (generate_video, edit_video, extend_video, upload_file). The pattern is uniform and predictable.
With 4 tools, the server is well-scoped for video generation. Each tool serves a necessary core function without redundancy or bloat.
The tool set covers the full video lifecycle: generate, edit, extend, and upload. There are no obvious missing operations for the stated domain.
Related MCP Connectors
MCP server for Grok Imagine AI video generation
MCP server for Google Veo AI video generation
MCP server for Kling AI video generation
MCP server for Hailuo (MiniMax) AI video generation
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for generating and editing images using xAI's Grok image model, supporting text prompts, batch generation, local files, and optional proxy configurations.234 npm29MIT
- AlicenseAqualityDmaintenanceMCP server for Google Veo 3.1 video generation. Supports text/video/image-based generation, extension, and interpolation with cost estimation and batch processing.425 npm1MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for generating and editing images using xAI's Grok API. Provides tools for image generation, editing, and style listing with configurable models and output options.-
- AlicenseAqualityDmaintenanceMCP server for generating and editing images and videos via DashScope/OpenAI-compatible APIs, with tools for text-to-image, image editing, text/video generation, and automatic local download.5MIT