About genrelay-mcp
genrelay-mcp is an MCP server for generating video and images through the GenRelay API, for users of clients such as Claude Desktop and Cursor. It supports several models and uses task IDs with `check_job` to retrieve videos that are still processing.
Key features
- 01Generate video from text
- 02Generate video from images
- 03Generate and edit images
- 04Check generation status by task ID
- 05List available models
Use cases
- 01Create video from a text prompt
- 02Use an image as video-generation input
- 03Generate or edit an image
- 04Check on a video job that is still running
MCP support
It exposes video and image generation, job-status checks, and model listing to MCP clients, handling requests through the GenRelay API.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y genrelay-mcpGENRELAY_API_KEYSecretYour GenRelay API key (https://genrelay.ai)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
4Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| size | string | No | Pixel size as "WxH", e.g. "1280x720". Aspect ratio is inferred from it. |
| tier | enum | No | Resolution tier. Worth setting: pricing is per tier, and a size matching no tier falls back to the model's base rate.720p | 1080p | 4k |
| model | enum | No | Which video model to use.veo_3_1 | veo_3_1-fl | veo_3_1-components | grok-imagine-video-1-5-preview | grok-imagine-1-0-video | omni-flash | omni_flash_abra_edit |
| prompt | string | Yes | What the video should show. |
| seconds | integer | No | Clip length in seconds (default 4). |
| reference_images | array | No | HTTPS or data: URLs to guide generation (image-to-video). |
Details
From the project READMEgenrelay-mcp
MCP server for GenRelay — generate video and images from Claude Desktop, Cursor, or any MCP client.
One server, several models: Veo 3.1, Grok Imagine, Omni Flash, Nano Banana Pro/2, GPT Image 2.
Install
Nothing to install — point your MCP client at it with npx.
Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"genrelay": {
"command": "npx",
"args": ["-y", "genrelay-mcp"],
"env": { "GENRELAY_API_KEY": "sk-..." }
}
}
}
Cursor — .cursor/mcp.json:
{
"mcpServers": {
"genrelay": {
"command": "npx",
"args": ["-y", "genrelay-mcp"],
"env": { "GENRELAY_API_KEY": "sk-..." }
}
}
}
Get a key at genrelay.ai. Restart the client after editing the config.
Tools
| Tool | What it does |
|---|---|
generate_video | Text-to-video and image-to-video. Returns the clip, or a task id if it's still running |
generate_image | Image generation and editing. Returns the picture inline |
check_job | Pick up a job by task id |
list_models | What's available and what each model is for |
Then just ask:
Generate an 8-second video of a neon fox running through a rainy city at night, 1080p
About the wait
Video generation takes 1–5 minutes — longer than an MCP tool call is allowed to run. So generate_video waits as long as it safely can, then hands back a task id:
Still generating — this is normal for video.
task id: task_abc123
status: in_progress
progress: 35%
Call check_job with task id "task_abc123" in a minute or two.
That's a normal outcome, not a failure. The job keeps running server-side — use check_job, don't resubmit (resubmitting bills a second time).
Images usually finish inside the budget and come back inline.
Models
Video
| Model | Notes |
|---|---|
veo_3_1 | Google Veo 3.1 — highest quality, with audio |
veo_3_1-fl | first/last frame — supply both endpoints |
veo_3_1-components | component-guided |
grok-imagine-video-1-5-preview | xAI Grok Imagine 1.5 |
grok-imagine-1-0-video | xAI Grok Imagine 1.0 |
omni-flash | fast, good for longer clips |
omni_flash_abra_edit | video editing from a source video |
Image — nano-banana-pro, nano-banana-2, gpt-image-2
Tiers: images 1k/2k/4k, Veo video 720p/1080p/4k. Pricing is per tier, and a size matching no tier falls back to the model's base rate — so set tier explicitly when cost matters.
Configuration
| Variable | |
|---|---|
GENRELAY_API_KEY | required |
GENRELAY_BASE_URL | optional, defaults to https://genrelay.ai/v1 |
Also available
- Python SDK —
pip install genrelay - JavaScript/TypeScript SDK —
npm install genrelay - Chat & image edits are OpenAI-compatible: point the official
openaipackage athttps://genrelay.ai/v1
Development
npm install
npm run build
node test/smoke.mjs # boots the server and speaks MCP to it
FAQ
What is genrelay-mcp? An MCP server that lets Claude Desktop, Cursor and other MCP clients generate video and images through the GenRelay API.
Which clients work? Any MCP client that can launch a stdio server with npx -y genrelay-mcp, including Claude Desktop and Cursor.
How do I get an API key? Sign up at genrelay.ai and create a key in the console. Set it as GENRELAY_API_KEY.
How is it billed? Prepaid credits in USD, pay as you go. See Pricing.
A video is still running. Do I resubmit? No. Use check_job with the task id. Resubmitting is billed again.
Where is it listed? npm and the official MCP Registry as io.github.gaoruitech/genrelay-mcp.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.