grok-imagine-mcp
The grok-imagine-mcp server provides AI agents with access to Grok Imagine models on RunAPI for image and video generation, editing, and utility tasks.
text_to_image: Generate images from a text prompt, with aspect ratio options.text_to_video: Generate videos from a text prompt, with aspect ratio, motion style (fun,normal,spicy), and output resolution (480p,720p) options.image_to_video: Convert a static image into a video, with aspect ratio, motion style, and resolution controls.edit_image: Apply edits to an existing image.extend_video: Lengthen an existing video (6 or 10 seconds extension).upscale_image: Increase the resolution/quality of an existing image.get_task: Fetch the current status and result payload for any previously created task by task ID.check_pricing: Look up current pricing for any Grok Imagine model and endpoint — no API key required.Async or synchronous execution: All creation tools support a
waitflag to poll until completion or return immediately with a task ID. Configurable viatimeout_msandpoll_interval_ms.
Supported model variants: grok-imagine-text-to-image, grok-imagine-text-to-video, grok-imagine-image-to-video, grok-imagine-edit-image.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grok-imagine-mcp generate an image of a cat wearing a wizard hat"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Why This Package?
@runapi.ai/grok-imagine-mcp is a focused Model Context Protocol server for the Grok Imagine model line on RunAPI.
It gives MCP-compatible assistants direct access to 7 endpoints and 7 model variants without loading the full RunAPI catalog.
Use this per-model server when an agent should stay scoped to Grok Imagine. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.
Related MCP server: GPT Image MCP Server
Install
Add it to Claude Code:
claude mcp add grok-imagine -s user -- npx -y @runapi.ai/grok-imagine-mcpUse project scope when the server should be shared with a repository:
claude mcp add grok-imagine -s project -- npx -y @runapi.ai/grok-imagine-mcpCodex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:
{
"mcpServers": {
"grok-imagine": {
"command": "npx",
"args": ["-y", "@runapi.ai/grok-imagine-mcp"]
}
}
}check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login.
Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.
Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.
Tools
Tool | Auth | Purpose |
| Yes | Create a Grok Imagine edit image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine extend video task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine image to video task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine segment map task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine text to video task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Create a Grok Imagine upscale image task and optionally wait for a terminal status. Returns the task id, status, and output URLs. |
| Yes | Fetch the current status and latest payload for an existing task. |
| No | Look up current pricing for a Grok Imagine model and endpoint. |
Models
Grok Imagine covers 7 model variants across 7 endpoints. Each tool accepts the models listed for it:
Tool | Models |
|
|
| no model parameter |
|
|
|
|
|
|
|
|
| no model parameter |
Model availability can change between releases. Use check_pricing or the Grok Imagine model page for the current catalog view.
Agent Prompts
Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.
Create a task
Run a Grok Imagine edit image task with RunAPI.The assistant can call check_pricing, then edit_image, and return the task id, status, and output URLs.
Submit without waiting
Create the task but don't wait for it to finish.The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.
Check pricing before creating
Check current Grok Imagine pricing, then create the task if it matches my request.The assistant calls check_pricing and can link to the Grok Imagine model page for the canonical catalog entry.
Configuration
The server resolves auth in this order:
RUNAPI_API_KEYenvironment variable, useful for headless and CI hosts~/.config/runapi/config.json, created by the MCPlogintool orrunapi loginNo key, which still allows
check_pricing
The config file is normally managed by login. A pre-provisioned headless config can use:
{
"apiKey": "your_runapi_key"
}Do not commit real API keys.
Links
Resource | URL |
Grok Imagine model page | |
npm package | |
GitHub repository | |
RunAPI MCP overview | |
RunAPI docs |
License
Licensed under the Apache License, Version 2.0.
Available Tools
10 toolscheck_pricingA
Look up RunAPI pricing for the grok-imagine model line.
Inputs: model, action.
edit_imageB
Create a Grok Imagine task on RunAPI (edit image). Returns a task id, status, and output URLs.
Inputs: wait, model, prompt, timeout_ms, +8 more.
extend_videoC
Create a Grok Imagine task on RunAPI (extend video). Returns a task id, status, and output URLs.
Inputs: prompt (required), start_seconds (required), source_task_id (required), extension_duration_seconds (required), +4 more.
get_taskB
Fetch the current status and latest result payload for a grok-imagine task.
Inputs: action (required), task_id (required).
image_to_videoB
Create a Grok Imagine task on RunAPI (image to video). Returns a task id, status, and output URLs.
Inputs: wait, index, model, prompt, +11 more.
loginA
Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.
Inputs: force.
segment_mapC
Create a Grok Imagine task on RunAPI (segment map). Returns a task id, status, and output URLs.
Inputs: wait, model, image_url, timeout_ms, +3 more.
text_to_imageB
Create a Grok Imagine task on RunAPI (text to image). Returns a task id, status, and output URLs.
Inputs: prompt (required), wait, model, enable_pro, +5 more.
text_to_videoB
Create a Grok Imagine task on RunAPI (text to video). Returns a task id, status, and output URLs.
Inputs: prompt (required), wait, model, timeout_ms, +8 more.
upscale_imageB
Create a Grok Imagine task on RunAPI (upscale image). Returns a task id, status, and output URLs.
Inputs: source_task_id (required), wait, timeout_ms, callback_url, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
The seven task-creation tools share identical boilerplate descriptions ("Create a Grok Imagine task on RunAPI (...)") and identical return shapes, so the agent must rely almost entirely on the tool names to distinguish them. The names themselves are modality-specific (text_to_image vs edit_image vs upscale_image vs image_to_video vs extend_video), which is mostly clear, though 'segment_map' is opaque and edit_image/upscale_image overlap conceptually.
Conventions are mixed: login, get_task, check_pricing, edit_image, extend_video, upscale_image follow a verb_noun style, while text_to_image, image_to_video, text_to_video, and segment_map are noun-phrase/operation names with no verb. It's readable but not a single predictable pattern, and the '_to_' forms sit awkwardly next to the verb-first ones.
Ten tools is well-scoped for an async generation service: one auth tool, one pricing lookup, one status poller, and one tool per generation mode. Each tool earns its place and there is no filler.
Auth, pricing, task polling, and seven generation modes are covered, but the async task lifecycle has notable gaps: there is no list_tasks, cancel_task, or delete, so an agent that loses a task id or needs to cancel a runaway job is stuck. Result retrieval is only via get_task, with no download/save helper.
Maintenance
Related MCP Connectors
Generate and edit images, create videos, quote credit costs, and retrieve private results.
Generate images, videos and music with model discovery, cost estimates and asynchronous results.
Make images and videos, price requests, list AI models and read your balance, from one API key.
130+ AI models for image, video, music, and audio — 18 model families, one RunAPI account.
Related MCP Servers
AlicenseAqualityFmaintenanceEnables AI video and image generation through the Runway API. Supports video generation from images and text prompts, image creation, video upscaling and editing, and task management.718 npm23MIT- AlicenseAqualityBmaintenanceEnables creating and managing GPT Image tasks (edit and text-to-image) via RunAPI, with options to poll status and check pricing.5136 npmApache 2.0
- AlicenseBqualityBmaintenanceEnables creating and polling Luma video modification tasks, fetching task status, and checking pricing via the RunAPI API.358 npmApache 2.0
- AlicenseAqualityBmaintenanceEnables image editing, remixing, and text-to-image generation using Qwen 2 models via RunAPI. Supports task polling and pricing checks.5109 npmApache 2.0