# 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](https://github.com/pongsakornp/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)

```bash
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

```bash
git clone https://github.com/pongsakornp/grok-media-mcp.git
cd grok-media-mcp
npm install
npm run build
```

## Usage

### OpenCode (`opencode.jsonc`)

```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`)

```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`)

```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

```bash
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](LICENSE).