grok-video-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grok-video-mcp Generate a video of a golden retriever running on a beach."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
grok-media-mcp
MCP server that gives AI agents xAI Grok media generation — images and video. Submit a prompt, get a real file back. Works with OpenCode, Claude Desktop, Cursor, VS Code, and any MCP client.
Companion to vision-mcp: one agent can generate a clip or image and verify it — a full media loop.
Why
Text-based agents can't generate media. grok-media-mcp exposes xAI's
grok-imagine-video and grok-imagine-image models as plain MCP tools so any
agent can produce real images and video clips from a prompt — no shell
scripts, no manual API calls, no hand-rolled polling loops.
Related MCP server: mcp-media-engine
Tools
Tool | What it does |
| Submit a generation → returns |
| Poll: |
| Download the finished clip to disk |
| Submit + poll + download in one call (agent-friendly) |
| Generate an image — synchronous, returns the saved file path (~10-30s, ~$0.06) |
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-media-mcpnpx 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-media-mcp.git
cd grok-media-mcp
npm install
npm run buildUsage
OpenCode (opencode.jsonc)
{
"mcp": {
"grok-media-mcp": {
"type": "local",
"command": ["npx", "-y", "github:pongsakornp/grok-media-mcp"],
"environment": {
"XAI_API_KEY": "xai-..."
},
"enabled": true
}
}
}Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"grok-media-mcp": {
"command": "npx",
"args": ["-y", "github:pongsakornp/grok-media-mcp"],
"env": {
"XAI_API_KEY": "xai-..."
}
}
}
}VS Code / Cursor (.vscode/mcp.json)
{
"servers": {
"grok-media-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:pongsakornp/grok-media-mcp"],
"environment": {
"XAI_API_KEY": "xai-..."
}
}
}
}Keys live in the MCP config — no shell profile edits needed.
Configuration
Env var | Default | Description |
| — | required — xAI API key |
|
| Model ( |
|
| Image model ( |
|
| Where media is saved |
|
| Max wait for a generation |
|
| Initial poll interval |
|
| Max poll interval (×1.5 backoff) |
How it works
Video — 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 bytesgenerate_and_wait encapsulates submit → poll (5s→30s backoff, progress
reported) → download → save, returning the file path.
Images — synchronous, one call:
POST /v1/images/generations → { data: [{ url, mime_type }], usage }
GET image.url → jpeg/png bytesgenerate_image encapsulates generate → download → save in one call.
(Verified live: 1248×832 output, ~30s, ~$0.06/image.)
Pricing: video roughly $0.005 per second ($0.04 for an 8s clip),
images **$0.06 each** — an order of magnitude cheaper than Google Veo Lite
($0.05–0.08/s).
Development
npm run build # TypeScript → dist/
npm test # 28 tests (vitest)
npm run typecheck # tsc --noEmitTest coverage: config parsing, video + image request/response mapping (mocked fetch), polling backoff/timeout/FAILED handling, and the full MCP stdio protocol.
License
MIT — see LICENSE.
Available Tools
4 toolsgenerate_and_waitGenerate video and waitA
Submit a Grok video generation, poll until complete (up to timeoutSeconds), and return the downloaded file path. The one-call convenience for agents.
Inputs: prompt (required), duration, resolution, aspectRatio, +1 more.
generate_videoGenerate videoA
Submit a Grok video generation from a text prompt. Returns a requestId to poll with get_generation and download with get_video. Generation takes 1-5 minutes. ~$0.005/sec.
Inputs: prompt (required), duration, resolution, aspectRatio.
get_generationGet generation statusA
Poll the status of a Grok video generation by requestId. Returns PENDING, COMPLETED, or FAILED with progress when available.
Inputs: requestId (required).
get_videoGet videoA
Download a completed Grok video generation to disk. Returns the file path. Requires the generation to be COMPLETED.
Inputs: requestId (required), outDir.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear, distinct role: generate_video submits, get_generation polls status, get_video downloads, and generate_and_wait combines these steps. The purpose of each is unambiguous, even with the convenience wrapper.
Most tools follow a clear verb_noun pattern (generate_video, get_generation, get_video). generate_and_wait deviates with a compound verb phrase, but the style is still consistent and readable.
Four tools is ideal for a focused video generation service: submit, poll, download, and a convenience flow. Each tool earns its place without bloat.
The tool surface covers the full lifecycle of video generation: submit, check status, retrieve result, and a one-call convenience. No obvious gaps remain for the stated purpose.
Maintenance
Related MCP Connectors
MCP server for Grok Imagine AI video generation
Make animated videos by asking Claude, Cursor or any MCP client. Your AI writes it, we render it.
MCP server for Hailuo (MiniMax) AI video generation
MCP server for OpenAI Sora AI video generation
Related MCP Servers
- AlicenseAqualityBmaintenanceUse XAI's latest api functionalities with Grok MCP. It supports image understanding and generation, live search, latest models and more.2256MIT
- AlicenseAqualityCmaintenanceMCP server for AI-powered image, audio, and video generation, enabling media creation directly from Claude, Cursor, and other MCP clients.1141 npmMIT
- AlicenseAqualityCmaintenanceMCP server for generating, editing, and batch processing videos using xAI's Grok Imagine Video API, with support for text-to-video, image-to-video, and video editing via natural language prompts.4105 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA single-file MCP server that enhances Claude Desktop with real-time web and X search, multi-tool agent, and image/video generation via xAI's Grok.MIT