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

機能

• 動画生成（Text-to-Video）: テキストプロンプトから新規動画を生成
• 動画生成（Image-to-Video）: 画像を入力として動画を生成
• 動画編集: 既存動画をプロンプトで編集
• バッチ処理: CLIで複数動画を一括処理
• 多様なアスペクト比をサポート（16:9, 4:3, 1:1, 9:16 など）
• 解像度: 720p, 480p
• 動画長: 1〜15秒（編集時は元動画と同じ長さ）
• 非同期処理対応（ポーリングによる結果取得）

サポートモデル

必要条件

• Node.js 18.0.0 以上
• 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

設定

環境変数

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

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

注意: image_url と image_path は同時に指定できません。

edit_video

既存動画を編集します。

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

バッチ処理 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 オプション一覧

終了コード

バッチ設定ファイル

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

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
}

*image_url または image_path のいずれかを指定（同時指定不可）

3. Video Edit（動画編集）

{
  "prompt": "編集内容の説明",
  "video_url": "https://example.com/video.mp4",
  "output_path": "edited.mp4"
}

グローバル設定

リトライポリシー

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

設定例は examples/ ディレクトリを参照してください：

• batch-simple.json - 基本的な動画生成
• batch-image-to-video.json - 画像からの動画生成（URL指定）
• batch-local-images.json - ローカル画像からの動画生成
• batch-with-edits.json - 動画編集チェーン
• batch-social-media.json - SNS向けフォーマット

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

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

動画長の制限

非同期処理について

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: "..." } → ダウンロード

使用例

# テキストから動画生成
「猫がボールで遊んでいる」の5秒動画を16:9で生成して

# 画像から動画生成
この画像のキャラクターを歩かせる動画を作って

# 動画編集
この動画の背景を夜に変更して

API リファレンス

• ドキュメント: 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 1200000

Rate 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