grok-media-mcp
MCP server that gives AI agents xAI Grok media generation — images andvideo. Submit a prompt, get a real file back. Works with OpenCode, ClaudeDesktop, Cursor, VS Code, and any MCP client.
Companion to vision-mcp: oneagent 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'sgrok-imagine-video and grok-imagine-image models as plain MCP tools so anyagent can produce real images and video clips from a prompt — no shellscripts, no manual API calls, no hand-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) |
generate_image(prompt, model?, n?, size?, outDir?) |
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-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-media-mcp.git
cd grok-media-mcp
npm install
npm run build
Usage
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 |
|---|---|---|
XAI_API_KEY |
— | required — xAI API key |
GROK_VIDEO_MODEL |
grok-imagine-video |
Model (grok-imagine-video-1.5 = 1080p) |
GROK_IMAGE_MODEL |
grok-imagine-image-2.0 |
Image model (grok-imagine-image-quality = higher quality) |
GROK_OUTPUT_DIR |
~/.grok-media-mcp/output |
Where media is 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
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 bytes
generate_and_wait encapsulates submit → poll (5s→30s backoff, progressreported) → download → save, returning the file path.
Images — synchronous, one call:
POST /v1/images/generations → { data: [{ url, mime_type }], usage }
GET image.url → jpeg/png bytes
generate_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 --noEmit
Test coverage: config parsing, video + image request/response mapping (mockedfetch), polling backoff/timeout/FAILED handling, and the full MCP stdioprotocol.
License
MIT — see LICENSE.
