Overview

This MCP (Model Context Protocol) server provides a lightweight bridge between xAI’s Grok family of models and external tools for image analysis, image generation, and live web search. It implements a simple API that follows MCP conventions so agent frameworks and developer tools can call Grok models with structured context and tool invocations — for example, asking a model to analyze an image, generate a new image, or augment responses with web search results.

For developers building multimodal assistants, research prototypes, or content pipelines, the Grok MCP server centralizes model I/O, tool orchestration, and configuration. It abstracts the low-level details of calling the xAI endpoint (keys, payload formats) and exposes consistent endpoints and payload shapes that are easy to integrate with agents, UIs, or automation scripts.

Features

MCP-compliant API surface for invoking Grok models with context and tools
Image analysis: object/scene description, captioning, and structured annotations
Image generation: instruct-driven image synthesis (prompt → image)
Integrated web search tool to retrieve recent web content and citations
Simple configuration via environment variables or .env files
Docker-friendly — run locally or in cloud environments
Example request/response patterns suitable for agent integration

Installation / Configuration

Prerequisites:

Python 3.10+ (recommended)
Git
An API key for xAI Grok (set as XAI_API_KEY). If using web search, set a SEARCH_API_KEY for your search provider.

Typical setup:

# Clone the repository
git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

Environment variables (example .env):

# .env
XAI_API_KEY=sk-xxxxx
MCP_HOST=0.0.0.0
MCP_PORT=8080
ENABLE_WEB_SEARCH=true
SEARCH_API_KEY=search-xxxx

Run the server (example using uvicorn):

# If the repo exposes an ASGI app in app.main:app
uvicorn app.main:app --host ${MCP_HOST:-0.0.0.0} --port ${MCP_PORT:-8080} --reload

Docker example:

# Build and run with env-file
docker build -t grok-mcp .
docker run --env-file .env -p 8080:8080 grok-mcp

Available Resources

The server exposes a set of REST endpoints that map to MCP-style tool calls. Typical endpoints include:

Endpoint	Purpose
POST /mcp/v1/invoke	Generic MCP invocation: pass model name, context, and requested tools
POST /mcp/v1/image/analyze	Send an image (URL or base64) for analysis/captioning
POST /mcp/v1/image/generate	Request image generation from prompt and parameters
POST /mcp/v1/search	Perform a web search and return top results & snippets

Payloads follow JSON conventions. Images can be provided as public URLs or as base64-encoded data within the request body depending on the endpoint’s configuration.

Use Cases

Image content analysis for moderation

Scenario: A platform needs to classify uploaded images for policy compliance.
Example curl:

curl -X POST http://localhost:8080/mcp/v1/image/analyze \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {"url": "https://example.com/uploaded.jpg"},
    "tasks": ["safety_labels","caption","objects"]
  }'

Expected: A structured JSON response with captions, detected objects and confidence scores.

Image-generation assistant

Scenario: A chatbot asks Grok to generate an image from a user prompt.
Example payload:

{
  "prompt": "A futuristic city skyline at sunset, vibrant colors, cinematic",
  "width": 1024,
  "height": 768,
  "style": "cinematic"
}

Call POST /mcp/v1/image/generate and receive a base64 image or a temporary URL.

Augmenting answers with web search

Scenario: The assistant needs up-to-date facts or citations.
Example curl:

curl -X POST http://localhost:8080/mcp/v1/search \
  -H "Authorization: Bearer $SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest Grok model capabilities 2024","limit":5}'

Response includes top snippets and source URLs that the Grok model can use when constructing answers.

Integration Tips

Treat the MCP server as a middleware: let your agent or application send a single MCP invocation that describes model input + requested tools and then handle the structured response.
For large volumes or production usage, run behind a process manager (systemd, Kubernetes) and enable TLS; keep API keys secure via secret stores.
Cache web-search results when feasible to reduce external API costs and latency.

For code samples, refer to the repository README and example clients in the examples/ folder (GitHub: https://github.com/merterbak/Grok-MCP).

Grok MCP Server: xAI Image & Web Search