Skip to main content
Glama

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

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

Install

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.

Available Tools

4 tools
generate_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

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Four tools is ideal for a focused video generation service: submit, poll, download, and a convenience flow. Each tool earns its place without bloat.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers