grok-video-mcp
MCP server that gives AI agents xAI Grok video generation — submit aprompt, poll the render, download the clip. Works with OpenCode, ClaudeDesktop, Cursor, VS Code, and any MCP client.
Companion to vision-mcp: oneagent can generate a clip and verify it — a full media loop.
Why
Text-based agents can't generate video. grok-video-mcp exposes xAI'sgrok-imagine-video models as plain MCP tools so any agent can produce areal video clip from a prompt — no shell scripts, no manual API calls, nohand-rolled polling loops.
Tools
| Tool | What it does |
|---|---|
generate_video(prompt, duration?, aspectRatio?, resolution?) |
Submit a generation → returns requestId |
get_generation(requestId) |
Poll: PENDING → COMPLETED / FAILED (with progress) |
get_video(requestId, outDir?) |
Download the finished clip to disk |
generate_and_wait(prompt, ...) |
Submit + poll + download in one call (agent-friendly) |
Requirements
- Node.js ≥ 18
- An xAI API key — https://console.x.ai (or docs.x.ai)
Install
npx from GitHub (recommended)
npx -y github:pongsakornp/grok-video-mcp
npx clones the repo, installs deps, auto-builds via the
preparescript,and runs the server over stdio.
From source
git clone https://github.com/pongsakornp/grok-video-mcp.git
cd grok-video-mcp
npm install
npm run build
Usage
OpenCode (opencode.jsonc)
{
"mcp": {
"grok-video-mcp": {
"type": "local",
"command": ["npx", "-y", "github:pongsakornp/grok-video-mcp"],
"environment": {
"XAI_API_KEY": "xai-..."
},
"enabled": true
}
}
}
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"grok-video-mcp": {
"command": "npx",
"args": ["-y", "github:pongsakornp/grok-video-mcp"],
"env": {
"XAI_API_KEY": "xai-..."
}
}
}
}
VS Code / Cursor (.vscode/mcp.json)
{
"servers": {
"grok-video-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:pongsakornp/grok-video-mcp"],
"environment": {
"XAI_API_KEY": "xai-..."
}
}
}
}
Keys live in the MCP config — no shell profile edits needed.
Configuration
| Env var | Default | Description |
|---|---|---|
XAI_API_KEY |
— | required — xAI API key |
GROK_VIDEO_MODEL |
grok-imagine-video |
Model (grok-imagine-video-1.5 = 1080p) |
GROK_VIDEO_OUTPUT_DIR |
~/.grok-video-mcp/output |
Where clips are saved |
GROK_VIDEO_TIMEOUT_MS |
900000 (15 min) |
Max wait for a generation |
GROK_VIDEO_POLL_BASE_MS |
5000 |
Initial poll interval |
GROK_VIDEO_POLL_MAX_MS |
30000 |
Max poll interval (×1.5 backoff) |
How it works
xAI's video API is async:
POST /v1/videos/generations → { request_id }
GET /v1/videos/{request_id} → poll until status: "done"
GET video.url → mp4 bytes
generate_and_wait encapsulates submit → poll (5s→30s backoff, progressreported) → download → save, returning the file path.
Pricing: roughly $0.005 per second of video (~$0.04 for an 8s clip)— an order of magnitude cheaper than Google Veo Lite ($0.05–0.08/s).
Development
npm run build # TypeScript → dist/
npm test # 23 tests (vitest)
npm run typecheck # tsc --noEmit
Test coverage: config parsing, xAI request/response mapping (mocked fetch),polling backoff/timeout/FAILED handling, and the full MCP stdio protocol.
License
MIT — see LICENSE.
