GrokMCP

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.

Release files for mcp-grok 2026.8.23.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-grok 2026.8.23.0
File	Size	Uploaded
mcp_grok-2026.8.23.0.tar.gz	32.7 kB	Aug 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcp-grok 2026.8.23.0
File	Interpreter	ABI	Platform	Reset
mcp_grok-2026.8.23.0-py3-none-any.whl 30.7 kB Aug 23, 2026	Python 3	none	any	Details

Total release size: 63.4 kB

Release files / mcp_grok-2026.8.23.0.tar.gz

Download URL	mcp_grok-2026.8.23.0.tar.gz
Size	32.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`84f31e93cd94cdcb6a14be3bd98ecf78b8fb02faa01f3c6e1a707cf4e4405720`
BLAKE2b-256 checksum How to use checksums	`9e4600e7be9a140176b09326ca2ce1a600da49c5cf83eea221f77c0a25e030cd`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`

Release files / mcp_grok-2026.8.23.0-py3-none-any.whl

Download URL	mcp_grok-2026.8.23.0-py3-none-any.whl
Size	30.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6923bce8ed751650e7f0033f49849ef9f335828d3b9cb68602243d0fff4278c1`
BLAKE2b-256 checksum How to use checksums	`0b92b2f2dd007d02e7139ed6a5bdd530ee5fb30e976c9eaf2dfcedbecfaf0188`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`