io.github.AceDataCloud/mcp-grok
MCP server for Grok Imagine AI video generation
Open source Repository Open in the app JSON README (API)
About
MCP server for Grok Imagine AI video generation
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- acedatacloud
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 2026.8.28.0
- Stars
- 1
- Open pull requests
- 7
- Last push
- 2026-08-28T10:39:46Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:01:39
- Updated
- 2026-08-29 03:01:39
- Origin id
io.github.AceDataCloud/mcp-grok
README
# GrokMCP
<!-- mcp-name: io.github.AceDataCloud/mcp-grok -->
[](https://pypi.org/project/mcp-grok/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **Grok** (xAI) — chat/reasoning/vision **and** Grok Imagine video generation, powered by the [AceDataCloud](https://platform.acedata.cloud) 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)
```bash
uvx mcp-grok
```
### Via pip
```bash
pip install mcp-grok
mcp-grok
```
## Configuration
Set your AceDataCloud API token (get one at <https://platform.acedata.cloud>):
```bash
export ACEDATACLOUD_API_TOKEN=your_api_token_here
```
### Claude Desktop / Claude Code
Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):
```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
```bash
pip install -e ".[dev,test]"
pytest --cov=core --cov=tools
ruff check .
```
## Documentation
<!-- canonical-documentation -->
[Documentation](https://platform.acedata.cloud/documents/grok)
## License
MIT — see [LICENSE](LICENSE).