Grok Imagine Video MCP Server

Grok Imagine视频MCP服务器

](https://www.npmjs.com/package/grok-imagine-video-mcp-server) 

用于xAI的Grok Imagine Video API的MCP（Model Context Protocol）服务器。支持从文本提示生成动画、从图像生成动画、编辑现有动画。

快速入门

最简单的方法是 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秒（编辑时长度与原视频相同）
• 支持异步处理（通过轮询获取结果）

支持模型

｜模型｜功能｜备注｜ |--------|------|------| | grok-imagine-video |生成・编集| 建议默认值 |

必要条件

• 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 视窗: %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"
      }
    }
  }
}

工具

生成视频

从文本提示或图像生成动画。

｜参数｜类型｜必需｜说明｜ |-----------|-----|------|------| | prompt ｜string｜是｜要生成的动画的说明文本｜ | output_path ｜string｜否｜输出文件路径（默认：generated_video.mp4）｜ | model 模型（默认值：grok-imagine-video） | duration 视频长度（1-15秒，默认值：5） | aspect_ratio ｜string｜否｜纵横比（默认值：16:9）｜ | resolution 分辨率（720p/480p，默认值：720p） | image_url | string | No | Image-to-Video用の入力画像URL | | image_path ｜string｜否｜本地图像文件路径（作为base64data URL发送到API）｜

注意: image_url 和 image_path 时褪色为此颜色。

edit_video

编辑现有视频。

｜参数｜类型｜必需｜说明｜ |-----------|-----|------|------| | prompt ｜string｜是｜编辑内容的说明｜ | video_url 是：要编辑的视频的URL（可公开访问，最多8.7秒） | output_path ｜string｜否｜输出文件路径（默认值：edited_video.mp4）｜ | model 模型（默认值：grok-imagine-video）

注意：编辑后的视频与原视频长度相同。duration 编辑时不能指定参数。

批处理CLI

命令格式

grok-imagine-video-batch  [options]

或通过npx：

npx grok-imagine-video-batch  [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 | - | ｜覆盖输出目录｜从设置文件｜ | --format | - | text\|json 输出格式 text | | --timeout | - | ` ｜超时（毫秒，最小值1000）｜ 600000 | | --max-concurrent | - | |最大同时実行数（1-10）| 2 | | --poll-interval | - | 轮询间隔（毫秒，最小值1000） 5000 | | --max-poll-attempts | - | 最大轮询次数 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
  }
}

作业定义架构

每个作业指定三种类型中的一种：

1.Text-to-Video（通过文本生成动画）

{
  "prompt": "生成したい動画の説明",
  "output_path": "output.mp4",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "model": "grok-imagine-video"
}

｜字段｜类型｜必需｜说明｜ |-----------|-----|------|------| | prompt 是视频说明文本 | output_path ｜string｜否｜输出文件名｜ | duration | number | No |动画长（1-15秒）| | aspect_ratio ｜string｜否｜长宽比｜ | resolution |string |否|解像度（720p/480p）| | model ｜string｜否｜模型名称｜

2.Image-to-Video（从图像生成动画）

指定URL时：

{
  "prompt": "画像をアニメーション化する説明",
  "image_url": "https://example.com/image.jpg",
  "output_path": "animated.mp4",
  "duration": 5
}

对于本地文件（base64data URL）：

{
  "prompt": "画像をアニメーション化する説明",
  "image_path": "./images/character.jpg",
  "output_path": "animated.mp4",
  "duration": 5
}

｜字段｜类型｜必需｜说明｜ |-----------|-----|------|------| | prompt 是=动画说明 | image_url ｜string｜否\*｜输入图像的URL（可公开访问）｜ | image_path 本地图像文件路径（作为base64data URL发送到API） | output_path ｜string｜否｜输出文件名｜ | duration | number | No |动画长（1-15秒）|

\*image_url 或 image_path 中选择另一种天花板类型

3. Video Edit（动画编集）

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

｜字段｜类型｜必需｜说明｜ |-----------|-----|------|------| | prompt ｜string｜是｜编辑内容的说明｜ | video_url 是：要编辑的视频的URL（最多8.7秒） | output_path ｜string｜否｜输出文件名｜

全局设置

｜字段｜类型｜说明｜默认｜ |-----------|-----|------|-----------| | output_dir ｜string｜输出目录｜ ./output | | max_concurrent | number |最大同时実行数（1-10）| 2 | | poll_interval 轮询间隔（ms） 5000 | | max_poll_attempts 最大轮询次数 120 | | default_model ｜string｜默认模型｜ grok-imagine-video | | default_duration 默认视频长度 5 | | default_aspect_ratio 默认纵横比 16:9 | | default_resolution 默认分辨率 720p |

重试策略

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

｜字段｜类型｜说明｜默认｜ |-----------|-----|------|-----------| | max_retries 最大重试次数 2 | | retry_delay_ms ｜number｜重试间隔（ms）｜ 1000 | | retry_on_errors ｜string\[\]｜重试对象错误｜上述参照｜

设置示例为 examples/ 请参阅目录：

• batch-simple.json -基本视频生成
• batch-image-to-video.json -从图像生成动画（URL指定）
• batch-local-images.json -从本地图像生成视频
• batch-with-edits.json -视频编辑链
• batch-social-media.json –SNS格式

支持的纵横比

宽高比｜用途例｜ |-------------|--------| | 16:9 横向宽屏、YouTube（默认设置） | 4:3 标准横向长度 | 1:1 | 正方形、Instagram| | 9:16 |縦长、TikTok、Reels、Stories | | 3:4 |縦长| | 3:2 / 2:3 | 写真比率 |

支持的分辨率

视频长度限制

操作｜最小｜最大｜默认｜ |------|------|------|-----------| | 生成（Text/Image-to-Video） | 1秒 | 15秒 | 5秒 | 编辑｜-｜8.7秒｜与原视频相同｜

关于异步处理

视频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参考

功能｜端点｜ |------|---------------| | 動画生成 | POST https://api.x.ai/v1/videos/generations | |动画编集| POST https://api.x.ai/v1/videos/edits | |结果取得| GET https://api.x.ai/v1/videos/{request_id} |

• 文档: 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

速率限制错误

减少并行数或调整重试设置：

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

相关项目

• grok想象图像mcp服务器 - 画像生成用MCP Server

许可证

麻省理工学院

作者

高岛俊二