XAI Server

A Model Context Protocol (MCP) server that brings xAI's Grok APIs to Claude Code. Generate images, chat with Grok, analyze images, search the web, and create videos—all from natural language prompts in your Claude Code session.

Features

Tool	Description
generate_image	Generate images using Grok Imagine
chat	Chat with Grok models (grok-3, grok-4, grok-3-mini)
analyze_image	Analyze and describe images with Grok Vision
live_search	Real-time web, news, and X/Twitter search
generate_video	Generate videos from text prompts

Prerequisites

• Node.js 18.0.0 or higher
• xAI API Key from x.ai/api
• Claude Code installed

Installation

Option 1: Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/joemccann/xai-mcp-server/main/install.sh | bash

This installs the server and automatically configures Claude Code. You'll be prompted for your xAI API key.

Option 2: npx from GitHub

No installation needed - runs directly from GitHub:

npx github:joemccann/xai-mcp-server

Option 3: npm Global Install

npm install -g @joemccann/xai-mcp-server

Option 4: Clone and Build

git clone https://github.com/joemccann/xai-mcp-server.git
cd xai-mcp-server
npm install

Configuration for Claude Code

Step 1: Get Your xAI API Key

1. Go to x.ai/api
2. Sign up or log in
3. Create an API key
4. Copy the key (starts with xai-)

Step 2: Configure Claude Code

Note: If you used the Quick Install (Option 1), this is already done for you.

Add the MCP server using the Claude CLI:

claude mcp add xai -e XAI_API_KEY=xai-your-key-here -- node ~/.xai-mcp-server/dist/index.js

For nvm users, use the absolute path to node:

claude mcp add xai -e XAI_API_KEY=xai-your-key-here -- $(which node) ~/.xai-mcp-server/dist/index.js

Verify it's configured:

claude mcp list

You should see:

xai: ... - ✓ Connected

Step 3: Restart Claude Code

Restart Claude Code to load the new MCP server. You should see the xAI tools available.

Usage

Once configured, you can use natural language to invoke xAI capabilities:

Image Generation

Generate an image of a cyberpunk cityscape at night with neon lights.

Using grok imagine, create a watercolor painting of a mountain landscape.

Generate 3 variations of a logo for a coffee shop called "Bean There".

Chat with Grok

Ask Grok to explain the theory of relativity in simple terms.

Have Grok write a haiku about programming.

Image Analysis

Analyze this image and describe what you see: https://example.com/photo.jpg

What text is visible in this screenshot: [image URL]

Live Search

Search for the latest news about SpaceX launches.

Find recent tweets about the new iPhone release.

Search the web for Python best practices 2024.

Video Generation

Generate a 5-second video of clouds moving across a blue sky.

Create a video animation of a bouncing ball.

Tool Reference

generate_image

Generate images from text descriptions using Grok Imagine.

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Text description of the image
n	number	No	1	Number of images (1-10)
model	string	No	grok-2-image-1212	Image generation model
aspect_ratio	string	No	-	Aspect ratio (e.g., "16:9", "1:1", "4:3")
response_format	string	No	url	Output format: "url" or "b64_json"

Example Response:

{
  "success": true,
  "images": [
    {
      "index": 1,
      "url": "https://api.x.ai/images/generated/abc123.png",
      "revised_prompt": "A detailed cyberpunk cityscape..."
    }
  ]
}

chat

Chat with Grok language models.

Parameter	Type	Required	Default	Description
message	string	Yes	-	Message to send to Grok
model	string	No	grok-3	Model: grok-3, grok-4, grok-3-mini
system_prompt	string	No	-	System context/instructions
temperature	number	No	0.7	Sampling temperature (0-2)
max_tokens	number	No	-	Maximum response tokens

analyze_image

Analyze images using Grok's vision capabilities.

Parameter	Type	Required	Default	Description
image_url	string	Yes	-	Image URL or base64 data URL
prompt	string	No	"Describe this image"	Question or instruction
detail	string	No	auto	Detail level: "low", "high", "auto"
model	string	No	grok-2-vision-1212	Vision model

live_search

Perform real-time web searches using Grok.

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query
sources	array	No	["web"]	Sources: "web", "news", "x"
date_range	object	No	-	Date filter: { start, end } (YYYY-MM-DD)
max_results	number	No	10	Maximum results (1-20)

generate_video

Generate videos from text descriptions.

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Video description
model	string	No	grok-imagine-video	Video generation model
duration	number	No	5	Duration in seconds (1-15)
image	string	No	-	Input image URL to animate
video	string	No	-	Input video URL to edit
aspect_ratio	string	No	-	Aspect ratio (e.g., "16:9")
wait_for_completion	boolean	No	true	Wait for video to finish

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Run the server directly
npm start

Testing

This project includes comprehensive unit tests with pretty table output:

# Run unit tests (mocked, no API calls)
npm run test

# Run tests with detailed output (shows every individual test)
npm run test:detailed

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run integration tests (requires XAI_API_KEY, makes real API calls)
npm run test:integration

Test Output Features:

• Color-coded results with status indicators (✓ PASS, ✗ FAIL)
• Performance metrics showing slowest/fastest test files
• Summary table with total stats
• Detailed mode shows individual test durations and suite hierarchy
• All tests use mocked APIs by default (no cost, no API key needed)

Project Structure

xai-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── xai-client.ts      # xAI API client with types
│   └── tools/
│       ├── generate-image.ts
│       ├── chat.ts
│       ├── vision.ts
│       ├── live-search.ts
│       └── generate-video.ts
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"XAI_API_KEY environment variable is required"

Re-add the MCP server with your API key:

claude mcp remove xai
claude mcp add xai -e XAI_API_KEY=xai-your-key-here -- $(which node) ~/.xai-mcp-server/dist/index.js

Tools not appearing in Claude Code

1. Run claude mcp list to check server status
2. If not listed, add it with claude mcp add (see Step 2 above)
3. For nvm users, use absolute node path: $(which node)
4. Ensure the project is built (npm run build)
5. Restart Claude Code completely

API errors

• Verify your API key is valid at x.ai
• Check you have sufficient API credits
• Some features may require specific API tier access

API Reference

This server uses the xAI API. For full API documentation, see:

• xAI API Reference
• Image Generation Guide

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Acknowledgments

• xAI for the Grok API
• Model Context Protocol for the MCP specification
• Anthropic for Claude Code