GrokMCP

# GrokMCP

<!-- mcp-name: io.github.AceDataCloud/mcp-grok -->

[![PyPI version](https://img.shields.io/pypi/v/mcp-grok.svg)](https://pypi.org/project/mcp-grok/)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=grok_mcp_readme_platform) 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 |

## Connect: hosted OAuth, API token, or local stdio

The hosted endpoint is `https://grok.mcp.acedata.cloud/mcp`. Choose one route for the MCP client:

| Route | When to use it | Credential setup |
|---|---|---|
| Hosted OAuth | The client supports remote MCP OAuth | Add only the URL, then sign in to AceDataCloud and approve access. No token needs to be pasted into client configuration. |
| Hosted API token | The client cannot finish OAuth, or you need an explicit integration credential | Send an AceDataCloud API token in the `Authorization: Bearer …` header. Keep it in a local secret store or environment variable. |
| Local stdio | The client runs a local MCP process | Install `mcp-grok` and pass `ACEDATACLOUD_API_TOKEN` to that process. It still calls the AceDataCloud API. |

The hosted service advertises OAuth metadata and Dynamic Client Registration (DCR). **DCR registers the client application; it is not an API key.** OAuth signs you in and the client sends the resulting Bearer token; it may reuse or create an API credential for the account. Browser sign-in still requires an AceDataCloud account. The hosted service can be metered: review [current service documentation](https://platform.acedata.cloud/documents/grok?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=grok_mcp_readme_quick_start) and displayed pricing before a real operation. Do not configure both an OAuth login and a fixed `Authorization` header for the same server.

### Hosted OAuth examples

- **Claude and Claude Desktop chat:** Add a remote custom connector in `Customize → Connectors → Add custom connector`, enter `https://grok.mcp.acedata.cloud/mcp`, select sign-in, and choose **Register automatically** if Claude asks how to register its OAuth client. Complete consent. Claude Desktop's local `claude_desktop_config.json` is a separate setup. [Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
- **Claude Code:** `claude mcp add --transport http --scope user grok https://grok.mcp.acedata.cloud/mcp`, then `claude mcp login grok`. Check `/mcp`. [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
- **Cursor:** Add a remote server with only `https://grok.mcp.acedata.cloud/mcp`. For a project, merge the entry below into `<project>/.cursor/mcp.json`; for personal use, use `~/.cursor/mcp.json`. [Cursor MCP guide](https://cursor.com/docs/mcp).
- **VS Code / Copilot:** Run **MCP: Add Server**, select HTTP, enter `https://grok.mcp.acedata.cloud/mcp`, then finish the browser sign-in. New portable workspace configs use `<project>/.mcp.json`; the VS Code-specific format below uses `<project>/.vscode/mcp.json` or the user profile. Check **MCP: List Servers**. [VS Code MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
- **Codex:** `codex mcp add grok --url https://grok.mcp.acedata.cloud/mcp`, then `codex mcp login grok`. Its user settings are in `~/.codex/config.toml`. [Official Codex MCP guide](https://developers.openai.com/codex/mcp/).

Cursor project config (OAuth):

```json
{
  "mcpServers": {
    "grok": {"url": "https://grok.mcp.acedata.cloud/mcp"}
  }
}
```

VS Code-specific workspace config (OAuth):

```json
{
  "servers": {
    "grok": {"type": "http", "url": "https://grok.mcp.acedata.cloud/mcp"}
  }
}
```

### Hosted API token

<!-- BEGIN TOKEN ONBOARDING -->
1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=grok_mcp_readme_api_key). Sign in, or register an account first.
2. Find **General application**. If it has not been created, choose **Initialize General Application**. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and [current pricing](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=grok_mcp_readme_models).
3. Copy the **API Key** from the application card, or open **Keys / Manage Keys → Create** to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
4. When creating a key, review **Expiration Time**, **Set Usage Limitation**, and **Allowed APIs**. Enable only the restrictions you need, allow the operations you will call, then click **Create** and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
5. Copy only the token value, without quotation marks, spaces, or `Bearer `. An API Key / API Token field expects this raw value; only a manually configured HTTP `Authorization` header needs the `Bearer ` prefix. A `platform-...` account-management token cannot replace a generation API key.

![Copy an application API key or open Manage Keys](https://raw.githubusercontent.com/AceDataCloud/NanoBananaDify/2522b2f57210597af2db866445319334a1677a23/_assets/tutorial/get-api-key-en.png)

![Create a separately named key with optional restrictions](https://raw.githubusercontent.com/AceDataCloud/NanoBananaDify/2522b2f57210597af2db866445319334a1677a23/_assets/tutorial/create-api-key-en.png)

Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.
<!-- END TOKEN ONBOARDING -->

A fixed Bearer header bypasses OAuth. If the header is invalid, remove it before trying browser sign-in; keep the saved credential private.

For Claude Code, the shell expands the token when you add the server; treat the saved user MCP config as a secret:

```bash
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user grok https://grok.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"
```

For a Claude Code project config, put a variable reference in `<project>/.mcp.json` and set that variable in the environment that launches Claude Code:

```json
{
  "mcpServers": {
    "grok": {
      "type": "http",
      "url": "https://grok.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}
```

Cursor uses a different environment-variable syntax in `~/.cursor/mcp.js