Grok MCP is a free, open-source AI agent skill. MCP server for xAI's Grok API with agentic tool calling, image and video generation, vision, and file support. - Agentic Tool Calling: Web search, X search, and code execution with multi-step reasoning - Multiple Grok Models: Access to Grok-4.1-Fast-Reasoning, Grok-4.1-Fast-Non-Reasoning, Grok-4-Fast, and more - Image and Video Generation: Create images and videos using Grok Imagine - Vision Capab

How do I install Grok MCP?

Install Grok MCP with a single command: npx mdskills install merterbak/grok-mcp. This downloads the skill files into your project and your AI agent picks them up automatically.

What platforms support Grok MCP?

Grok MCP works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.

Grok-MCP

Name: Grok MCP: AI Agent Skill
Rating: 8 (1 reviews)
Author: merterbak

MCP server for xAI's Grok API with agentic tool calling, image and video generation, vision, and file support.

Features

Agentic Tool Calling: Web search, X search, and code execution with multi-step reasoning
Multiple Grok Models: Access to Grok-4.1-Fast-Reasoning, Grok-4.1-Fast-Non-Reasoning, Grok-4-Fast, and more
Image and Video Generation: Create images and videos using Grok Imagine
Vision Capabilities: Analyze images with Grok's vision models
Files API: Upload, manage, and chat with documents
Stateful Conversations: Maintain conversation context as id across multiple requests

Prerequisites

Python 3.11 or higher
xAI API key (Get one here)
Astral UV

Installation

Clone the repository:

git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

Create a venv environment:

uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows

Install dependencies:

uv sync

Configuration

Claude Desktop Integration

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Filesystem MCP (Optional)

Claude Desktop can't send uploaded images in the chat to an MCP tool. The easiest way to give access to files directly from your computer is official Filesystem MCP server. After setting it up you’ll be able to just write the image’s file path (such as /Users/mert/Desktop/image.png) in chat and Claude can use it with any vision chat tool.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users//Desktop",
        "/Users//Downloads"
      ]
    }
  }
}

For stdio:

uv run python main.py

Docker:

docker compose up --build

Mcp Inspector:

mcp dev main.py

Available Tools

Note: For using images and files, you must provide paths to chat. See Filesystem MCP (Optional) for setup.

`list_models`

List all available Grok models.

`chat`

Standard chat completion.

Parameter	Type	Default	Description
`prompt`	str	required	Your message
`model`	str	grok-4	Model to use
`system_prompt`	str	None	System instruction
`store_messages`	bool	False	Enable conversation history

`chat_with_vision`

Analyze images with text.

Parameter	Type	Default	Description
`prompt`	str	required	Question about the image
`model`	str	grok-4	Vision model
`image_paths`	List[str]	None	Local image file paths
`image_urls`	List[str]	None	Image URLs
`detail`	str	auto	auto, low, or high

Returns: Content + usage with prompt_image_tokens

`generate_image`

Create or edit images from text.

Parameter	Type	Default	Description
`prompt`	str	required	Image description or edit instruction
`model`	str	grok-imagine-image	Image model
`image_path`	str	None	Local image path to edit
`image_url`	str	None	Image URL to edit
`n`	int	1	Number of images (1-10)
`aspect_ratio`	str	None	like "16:9", "1:1"

`generate_video`

Create or edit videos from text, images, or existing videos.

Parameter	Type	Default	Description
`prompt`	str	required	Video description or edit instruction
`model`	str	grok-imagine-video	Video model
`image_path`	str	None	Local image path to animate
`image_url`	str	None	Image URL to animate
`video_path`	str	None	Local video path to edit (max 20MB)
`video_url`	str	None	Video URL to edit
`duration`	int	None	Duration in seconds (1-15)
`aspect_ratio`	str	None	like "16:9", "4:3"
`resolution`	str	None	"720p" or "480p"

`web_search`

Agentic web search with autonomous research.

Parameter	Type	Default	Description
`prompt`	str	required	Search query
`model`	str	grok-4-1-fast	Model
`allowed_domains`	List[str]	None	Restrict to domains (max 5)
`excluded_domains`	List[str]	None	Exclude domains (max 5)
`enable_image_understanding`	bool	False	Analyze images in results
`include_inline_citations`	bool	False	Embed citations in text
`max_turns`	int	None	Limit reasoning turns

Returns: Content, citations, tool_calls, usage

`x_search`

Agentic X (Twitter) search.

Parameter	Type	Default	Description
`prompt`	str	required	Search query
`model`	str	grok-4-1-fast	Model
`allowed_x_handles`	List[str]	None	Only these handles (max 10)
`excluded_x_handles`	List[str]	None	Exclude handles (max 10)
`from_date`	str	None	Start date (DD-MM-YYYY)
`to_date`	str	None	End date (DD-MM-YYYY)
`enable_image_understanding`	bool	False	Analyze images
`enable_video_understanding`	bool	False	Analyze videos
`include_inline_citations`	bool	False	Embed citations
`max_turns`	int	None	Limit turns

Returns: Content, citations, tool_calls, usage

`grok_agent`

Unified agent combining files, images, and all agentic tools (web search, X search, code execution).

Parameter	Type	Default	Description
`prompt`	str	required	Your query
`model`	str	grok-4-1-fast	Model
`file_ids`	List[str]	None	Uploaded file IDs to search
`image_urls`	List[str]	None	Image URLs to analyze
`image_paths`	List[str]	None	Local image paths
`use_web_search`	bool	False	Enable web search
`use_x_search`	bool	False	Enable X search
`use_code_execution`	bool	False	Enable code execution
+ all web_search and x_search params

Returns: Content, citations, tool_calls, code_outputs, uploaded_file_ids, usage

`code_executor`

Execute Python code for calculations and analysis.

Parameter	Type	Default	Description
`prompt`	str	required	Task description
`model`	str	grok-4-1-fast	Model
`max_turns`	int	None	Limit turns

Returns: Content, tool_calls, code_outputs, usage

`stateful_chat`

Maintain conversation state across requests.

Parameter	Type	Default	Description
`prompt`	str	required	Your message
`model`	str	grok-4	Model
`response_id`	str	None	Previous response ID to continue a conversation
`system_prompt`	str	None	System instruction

Returns: Content, response_id, usage

`retrieve_stateful_response`

Retrieve a stored conversation.

`delete_stateful_response`

Delete a stored conversation.

`upload_file`

Upload a document (max 48 MB).

Parameter	Type	Default	Description
`file_path`	str	required	Local file path

Supported formats: .txt, .md, .py, .js, .csv, .json, .pdf, and more

`list_files`

List uploaded files with sorting.

Parameter	Type	Default	Description
`limit`	int	100	Max files to return
`order`	str	desc	asc or desc
`sort_by`	str	created_at	created_at, filename, or size

`get_file`

Get file metadata by ID.

`get_file_content`

Download file content by ID.

Parameter	Type	Default	Description
`file_id`	str	required	File ID
`max_bytes`	int	500000	Max bytes to return

`delete_file`

Delete a file by ID.

`chat_with_files`

Chat with uploaded documents using agentic document search.

Parameter	Type	Default	Description
`prompt`	str	required	Question about docs
`model`	str	grok-4-1-fast	Model
`file_ids`	List[str]	None	File IDs to search
`system_prompt`	str	None	System instruction

Returns: Content, citations, usage

License

This project is open source and available under the MIT License.

Grok MCP