Skip to main content
Glama
Grok Imagine Video MCP Server

Grok Imagine Video MCP Server

by ex-takashima

Grok Imagine Video MCP Server

npm version License: MIT

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-server

Related 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 を参照してください。

サポートモデル

モード

grok-imagine-video

grok-imagine-video-1.5

Text-to-Video

✅

✅

Image-to-Video

✅

✅

Reference-to-Video

✅

✅

R2V のプリセットボイス(reference_audios)

❌

✅

編集

✅

❌

延長

✅

❌

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

設定

環境変数

変数

必須

説明

XAI_API_KEY

Yes

xAI API キー

DEBUG

No

true でデバッグログを有効化

OUTPUT_DIR

No

動画のデフォルト出力ディレクトリ

VIDEO_POLL_INTERVAL

No

ポーリング間隔(ミリ秒、デフォルト: 5000)

VIDEO_MAX_POLL_ATTEMPTS

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

テキストプロンプトまたは画像から動画を生成します。

パラメータ

型

必須

説明

prompt

string

条件付き

生成する動画の説明テキスト。T2V/R2V では必須、I2V(画像指定時)では省略可

output_path

string

No

出力ファイルパス(デフォルト: generated_video.mp4)

model

string

No

モデル(デフォルト: grok-imagine-video)

duration

number

No

動画長(1-15秒、デフォルト: 8)

aspect_ratio

string

No

アスペクト比(デフォルト: 16:9)

resolution

string

No

解像度(480p/720p/1080p、デフォルト: 720p)

image_url

string

No

Image-to-Video用の入力画像URL

image_path

string

No

ローカル画像ファイルパス(base64 data URLとして送信。10MB超はFiles API経由で自動アップロード)

image_file_id

string

No

xAI Files API の File ID(Image-to-Video用)

reference_images

array

No

Reference-to-Video用の参照画像(各要素は url / path / file_id のいずれか)。プロンプト中では <IMAGE_0> … で参照

reference_audios

array

No

R2V用のプリセットボイス(最大3件、各要素は voice_id または url)。grok-imagine-video-1.5 限定。プロンプト中では <AUDIO_0> … で参照

注意: image_url / image_path / image_file_id はいずれか1つのみ指定できます。また、画像(I2V)と reference_images / reference_audios(R2V)も同時指定できません。reference_audios は単独指定(音声のみの R2V)も可能です。

edit_video

既存動画を編集します。

パラメータ

型

必須

説明

prompt

string

Yes

編集内容の説明

video_url

string

No*

編集する動画のURL(公開アクセス可能、最大8.7秒)

video_path

string

No*

ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード)

video_file_id

string

No*

xAI Files API の File ID(*いずれか1つを指定)

output_path

string

No

出力ファイルパス(デフォルト: edited_video.mp4)

model

string

No

モデル(デフォルト: grok-imagine-video)

注意: 編集後の動画は元動画と同じ長さになります。duration パラメータは編集時には指定できません。

extend_video

既存動画の続きを生成して延長します(grok-imagine-video 1.5)。

パラメータ

型

必須

説明

prompt

string

Yes

続きで何が起こるかの説明

video_url

string

No*

延長する動画のURL(公開アクセス可能 or base64 data URL、.mp4)

video_path

string

No*

ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード)

video_file_id

string

No*

xAI Files API の File ID(*いずれか1つを指定)

output_path

string

No

出力ファイルパス(デフォルト: extended_video.mp4)

model

string

No

モデル(デフォルト: grok-imagine-video)

duration

number

No

延長セグメントの長さ(2-10秒、デフォルト: 6)

upload_file

ローカルの画像・動画ファイルを xAI Files API にアップロードし、file_id を取得します。ファイルは非公開のまま保存され、image_file_id / reference_images[].file_id / video_file_id として再利用できます(同じファイルを何度も送り直す必要がありません)。

パラメータ

型

必須

説明

file_path

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 --version

CLI オプション一覧

オプション

短縮形

引数

説明

デフォルト

--output-dir

-

<path>

出力ディレクトリを上書き

設定ファイルから

--format

-

text|json

出力フォーマット

text

--timeout

-

<ms>

タイムアウト(ミリ秒、最小1000)

600000

--max-concurrent

-

<n>

最大同時実行数(1-10)

2

--poll-interval

-

<ms>

ポーリング間隔(ミリ秒、最小1000)

5000

--max-poll-attempts

-

<n>

最大ポーリング回数

120

--estimate-only

-

-

コスト見積もりのみ(実行しない)

-

--allow-any-path

-

-

任意の出力パスを許可(CI/CD用)

-

--help

-h

-

ヘルプメッセージ表示

-

--version

-v

-

バージョン表示

-

終了コード

コード

意味

0

成功(全ジョブ完了)

1

エラー(失敗またはキャンセルあり)

バッチ設定ファイル

{
  "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"
}

フィールド

型

必須

説明

prompt

string

Yes

動画の説明テキスト

output_path

string

No

出力ファイル名

duration

number

No

動画長(1-15秒)

aspect_ratio

string

No

アスペクト比

resolution

string

No

解像度(720p/480p)

model

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
}

フィールド

型

必須

説明

prompt

string

Yes

アニメーションの説明

image_url

string

No*

入力画像のURL(公開アクセス可能)

image_path

string

No*

ローカル画像ファイルパス(base64 data URLとして送信。10MB超はFiles API経由で自動アップロード)

image_file_id

string

No*

xAI Files API の File ID

output_path

string

No

出力ファイル名

duration

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
}

フィールド

型

必須

説明

prompt

string

Yes

動画の説明

reference_images

array

条件付き

参照画像(各要素は url / path / file_id のいずれか)。reference_audios があれば省略可

reference_audios

array

条件付き

プリセットボイス(最大3件、各要素は voice_id または url)。grok-imagine-video-1.5 限定

output_path

string

No

出力ファイル名

duration

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

フィールド

型

必須

説明

prompt

string

Yes

編集内容の説明

video_url

string

No*

編集する動画のURL(最大8.7秒)

video_path

string

No*

ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード)

video_file_id

string

No*

xAI Files API の File ID(*いずれか1つを指定)

output_path

string

No

出力ファイル名

5. Video Extension(動画延長)

{
  "operation": "extend",
  "prompt": "カメラが引いて街並みが見える",
  "video_url": "https://example.com/video.mp4",
  "output_path": "extended.mp4",
  "duration": 6
}

フィールド

型

必須

説明

operation

string

Yes

"extend" を指定(省略するとソース動画付きは編集扱い)

prompt

string

Yes

続きで何が起こるかの説明

video_url

string

No*

延長する動画のURL

video_path

string

No*

ローカル動画ファイルパス(.mp4、Files API 経由で自動アップロード)

video_file_id

string

No*

xAI Files API の File ID(*いずれか1つを指定)

output_path

string

No

出力ファイル名

duration

number

No

延長セグメントの長さ(2-10秒、デフォルト6)

video_url / video_path / video_file_id を持つジョブは既定で編集(edit)として扱われます。延長したい場合は "operation": "extend" を明示してください。

グローバル設定

フィールド

型

説明

デフォルト

output_dir

string

出力ディレクトリ

./output

max_concurrent

number

最大同時実行数(1-10)

2

poll_interval

number

ポーリング間隔(ms)

5000

max_poll_attempts

number

最大ポーリング回数

120

default_model

string

デフォルトモデル

grok-imagine-video

default_duration

number

デフォルト動画長

8

default_aspect_ratio

string

デフォルトアスペクト比

16:9

default_resolution

string

デフォルト解像度

720p

リトライポリシー

{
  "retry_policy": {
    "max_retries": 2,
    "retry_delay_ms": 1000,
    "retry_on_errors": ["rate_limit", "429", "500", "502", "503"]
  }
}

フィールド

型

説明

デフォルト

max_retries

number

最大リトライ回数

2

retry_delay_ms

number

リトライ間隔(ms)

1000

retry_on_errors

string[]

リトライ対象エラー(エラーメッセージへの部分一致)

["rate_limit", "timeout", "429", "503", "service_unavailable", "internal_error"]

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向けフォーマット

サポートされているアスペクト比

アスペクト比

用途例

16:9

横長ワイドスクリーン、YouTube(デフォルト)

4:3

標準的な横長

1:1

正方形、Instagram

9:16

縦長、TikTok、Reels、Stories

3:4

縦長

3:2 / 2:3

写真比率

サポートされている解像度

解像度

説明

1080p

フルHD画質(grok-imagine-video-1.5 の T2V/I2V 限定。R2V は 720p 上限。基本モデルでは "1080p video resolution is not available for this model." になります)

720p

HD画質(デフォルト)

480p

標準画質

動画長の制限

操作

最小

最大

デフォルト

生成(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

grok-imagine-video

$0.05

$0.07

非対応

grok-imagine-video-1.5

$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は非同期で動作します:

  1. リクエスト送信: 動画生成/編集リクエストを送信

  2. request_id 取得: APIから request_id が返される

  3. ポーリング: 定期的に結果を確認(デフォルト: 5秒間隔)

  4. 結果取得: 完了後、動画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)

POST https://api.x.ai/v1/videos/generations

動画編集

POST https://api.x.ai/v1/videos/edits

動画延長

POST https://api.x.ai/v1/videos/extensions

結果取得

GET https://api.x.ai/v1/videos/{request_id}

開発

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 1200000

Rate Limit エラー

並列数を減らすか、リトライ設定を調整してください:

{
  "max_concurrent": 1,
  "retry_policy": {
    "max_retries": 3,
    "retry_delay_ms": 5000,
    "retry_on_errors": ["rate_limit", "429"]
  }
}

関連プロジェクト

ライセンス

MIT

作者

Junji Takashima takajyun00@gmail.com

Available Tools

4 tools
edit_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

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    With 4 tools, the server is well-scoped for video generation. Each tool serves a necessary core function without redundancy or bloat.

    Completeness5/5

    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

    Related MCP Servers