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.

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 prepare script, 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, 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 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 (mocked fetch), polling backoff/timeout/FAILED handling, and the full MCP stdio protocol.

License

MIT — see LICENSE.