GrokMCP

PyPI version Python License: MIT

A Model Context Protocol (MCP) server for Grok (xAI) — chat/reasoning/vision and Grok Imagine video generation, powered by the AceDataCloud API.

Chat with Grok models, or generate short AI videos from a text prompt or a still image — directly from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

Features

Chat / Reasoning / Vision — Talk to Grok 4.5 / Grok 4 / Grok 3 models, with image input and tool calling
Text to Video — Generate a video clip from a text description
Image to Video — Animate a reference image into a video
Async task tracking — Submit a job, poll for the result, single or batch
stdio & HTTP transports — Local stdio for desktop clients, HTTP for remote hosting

Tools

Tool	Description
`grok_chat_completions`	Chat completion (reasoning / vision / tool calling) with Grok chat models.
`grok_text_to_video`	Generate a video from a text prompt (any model except `grok-imagine-video-1.5:official`).
`grok_image_to_video`	Generate a video from an input image (+ optional motion prompt).
`grok_get_task`	Query the status/result of a single generation task.
`grok_get_tasks_batch`	Query the status/result of multiple tasks at once.
`grok_list_models`	List available models and their capabilities.
`grok_list_actions`	List all tools and example workflows.
`grok_get_prompt_guide`	Tips for writing effective video prompts.

Models

Chat (`grok_chat_completions`)

Model	Notes
`grok-4.5`	Default — latest flagship reasoning model
`grok-4`	Previous flagship reasoning model
`grok-3`	Earlier-generation model

Video

Model	Text→Video	Image→Video	Notes
`grok-imagine-video-1.5-fast:reverse`	✅	✅	Default. Fastest & cheapest. 6-30s, duration-banded billing.
`grok-imagine-video:reverse`	✅	✅	Standard. 1-15s, billed per output second.
`grok-imagine-video:official`	✅	✅	Official endpoint, higher fidelity. 1-15s, per second.
`grok-imagine-video-1.5:official`	❌	✅	Official image-to-video only (requires `image_url`). Up to 1080p, per second.

Parameters

Parameter	Applies to	Values
`prompt`	both	Text description (required for text-to-video)
`image_url`	image-to-video	Input image URL (required for `-1.5-preview`)
`reference_image_urls`	image-to-video	Optional list of style/content reference images
`aspect_ratio`	both	`1:1`, `16:9` (default), `9:16`, `4:3`, `3:4`, `3:2`, `2:3`
`resolution`	both	`480p` (default), `720p`, `1080p`
`duration`	both	`grok-imagine-video-1.5-fast:reverse`: `6`–`30`s; other models: `1`–`15`s (default `6`)
`callback_url`	both	Optional async webhook

Installation

Via uvx (recommended)

uvx mcp-grok

Via pip

pip install mcp-grok
mcp-grok

Configuration

Set your AceDataCloud API token (get one at https://platform.acedata.cloud):

export ACEDATACLOUD_API_TOKEN=your_api_token_here

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "grok": {
      "command": "uvx",
      "args": ["mcp-grok"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Remote (HTTP)

A hosted Streamable HTTP endpoint is available at:

https://grok.mcp.acedata.cloud/mcp

Environment Variables

Variable	Description	Default
`ACEDATACLOUD_API_TOKEN`	API token (required)	—
`ACEDATACLOUD_API_BASE_URL`	API base URL	`https://api.acedata.cloud`
`GROK_DEFAULT_MODEL`	Default model	`grok-imagine-video-1.5-fast:reverse`
`GROK_REQUEST_TIMEOUT`	Request timeout (seconds)	`180`
`MCP_SERVER_NAME`	MCP server name	`grok`
`MCP_TRANSPORT`	Transport mode (`stdio`/`http`)	`stdio`
`LOG_LEVEL`	Logging level	`INFO`

Usage Notes

Generation is asynchronous: the generation tools return a task_id quickly. Poll with grok_get_task(task_id) until the state is succeeded and the video_url is available.
Generation typically takes ~30 seconds to a few minutes.
Keep resolution at 480p and duration short for faster, cheaper iterations.

Development

pip install -e ".[dev,test]"
pytest --cov=core --cov=tools
ruff check .

Documentation

License

MIT — see LICENSE.