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–30s; other models: 1–15s (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_idquickly. Poll withgrok_get_task(task_id)until the state issucceededand thevideo_urlis available. - Generation typically takes ~30 seconds to a few minutes.
- Keep
resolutionat480panddurationshort for faster, cheaper iterations.
Development
pip install -e ".[dev,test]"
pytest --cov=core --cov=tools
ruff check .
License
MIT — see LICENSE.
1 maintainer
Release files for mcp-grok 2026.8.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mcp_grok-2026.8.17.0.tar.gz | 32.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mcp_grok-2026.8.17.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 63.1 kB
Release files / mcp_grok-2026.8.17.0.tar.gz
| Download URL | mcp_grok-2026.8.17.0.tar.gz |
|---|---|
| Size | 32.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6a03d602c5fc6acf582c943dbaa18ed54f780c7980c9772a54ecae7ddb674f9
|
|
BLAKE2b-256 checksum How to use checksums |
aa7bc62ba3047a8e16c908f33a471beca38d8f614d768b6c1bb7c65d894d0a29
|
| Upload date | |
|
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.17.0-py3-none-any.whl
| Download URL | mcp_grok-2026.8.17.0-py3-none-any.whl |
|---|---|
| Size | 30.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
066a13b87e965037f62b202f346f4c58e97ec4e306f2d5020361055152aa32fc
|
|
BLAKE2b-256 checksum How to use checksums |
ff2a55f677d550741aeba4d4d84e8ccf98992d77edeed351dd9fc9c48fb22927
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.12.3
|
