grok-video-mcp

MCP server that gives AI agents xAI Grok video generation — submit a prompt, poll the render, download the clip. Works with OpenCode, Claude Desktop, Cursor, VS Code, and any MCP client.

Companion to vision-mcp: one agent can generate a clip and verify it — a full media loop.

Why

Text-based agents can't generate video. grok-video-mcp exposes xAI's grok-imagine-video models as plain MCP tools so any agent can produce a real video clip from a prompt — no shell scripts, no manual API calls, no hand-rolled polling loops.

Related MCP server: mcp-media-engine

Tools

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 prepare script, 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

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, progress reported) → 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.