Grok-MCP-Claude

Grok MCP server optimized for Claude Desktop — clean, single-file implementation using xAI's Grok for real-time web/X search and image generation.

Concept

Claude thinks, Grok searches.

Claude Desktop handles conversation, memory, and reasoning. Grok provides what Claude can't — real-time web search, X (Twitter) search, and image/video generation.

Features

Tool	Description
grok_search	Real-time web and X (Twitter) search
grok_chat	Chat with vision, file, and code execution support
grok_agent	Multi-tool agent combining search, code execution, files, and images
generate_image	Image generation with img2img support
generate_video	Video generation with img2video and video2video support
manage_files	Upload, list, retrieve, and delete files on xAI

Requirements

• Python 3.10+
• xAI API key
• Claude Desktop

Installation

git clone https://github.com/yourname/grok-mcp-claude.git
cd grok-mcp-claude
pip install -r requirements.txt

Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "grok": {
      "command": "python",
      "args": ["/path/to/grok-mcp-claude/grok.py"],
      "env": {
        "XAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tool Reference

grok_search

Real-time search via web or X (Twitter).

Parameter	Default	Description
prompt	required	Search query
platform	"web"	"web" or "x"
model	DEFAULT_SEARCH_MODEL	Model to use
allowed_targets	None	Whitelist of domains (web) or handles (X)
excluded_targets	None	Blacklist of domains (web) or handles (X)
from_date	None	Start date DD-MM-YYYY (X only)
to_date	None	End date DD-MM-YYYY (X only)
include_inline_citations	False	Return inline citations

---

grok_chat

General-purpose chat with optional vision, file, and code execution.

Parameter	Default	Description
prompt	required	User message
model	DEFAULT_CHAT_MODEL	Model to use
system_prompt	None	System prompt
file_ids	None	xAI file IDs to attach
image_paths	None	Local image paths
image_urls	None	Image URLs
response_id	None	Previous response ID for stateful chat
use_code_execution	False	Enable code execution

---

grok_agent

Multi-tool agent. Combine web search, X search, code execution, files, and images freely.

Parameter	Default	Description
prompt	required	User message
model	DEFAULT_SEARCH_MODEL	Model to use
use_web_search	False	Enable web search
use_x_search	False	Enable X search
use_code_execution	False	Enable code execution
allowed_targets	None	Whitelist of domains or handles
excluded_targets	None	Blacklist of domains or handles
file_ids	None	xAI file IDs to attach
image_paths	None	Local image paths
image_urls	None	Image URLs
system_prompt	None	System prompt
include_inline_citations	False	Return inline citations
max_turns	None	Max search iterations

---

generate_image

Generate images. Pass image_path or image_url for img2img.

Parameter	Default	Description
prompt	required	Generation prompt
model	DEFAULT_IMAGE_MODEL	Model to use
n	1	Number of images
image_path	None	Local image for img2img
image_url	None	Image URL for img2img
aspect_ratio	None	e.g. "16:9", "1:1", "9:16"

---

generate_video

Generate videos from text, image, or video.

Parameter	Default	Description
prompt	required	Generation prompt
model	DEFAULT_VIDEO_MODEL	Model to use
image_path / image_url	None	Source image for img2video
video_path / video_url	None	Source video for video2video
duration	None	Duration in seconds
aspect_ratio	None	Aspect ratio
resolution	None	Resolution

---

manage_files

Manage files on xAI.

Action	Required params	Description
upload	file_path	Upload a file
list	—	List uploaded files
get_info	file_id	Get file metadata
get_content	file_id	Get file content
delete	file_id	Delete a file

Models

DEFAULT_CHAT_MODEL   = "grok-4-1-fast-non-reasoning"
DEFAULT_SEARCH_MODEL = "grok-4-1-fast-reasoning"
DEFAULT_IMAGE_MODEL  = "grok-imagine-image"
DEFAULT_VIDEO_MODEL  = "grok-imagine-video"

License

MIT