grok2api-mcp

A Node.js/TypeScript-based MCP (Model Context Protocol) Server that provides an interface to the Grok AI API (X/Twitter's AI model). This server runs over stdio and acts as a bridge between MCP clients (like Claude Desktop) and Grok's OpenAI-compatible API endpoints.

中文文档

Features

• X Search - Search and summarize X (Twitter) content using Grok
• General Search - General web search and summarization
• Image Generation - Generate images via Grok's image API
• Video Generation - Generate videos via Grok's video API

Requirements

• Node.js >= 18
• Grok API access (API token from X.AI)

Installation

Quick Start with npx

npx grok2api-mcp

Global Installation

npm install -g grok2api-mcp
grok2api-mcp

From Source

git clone https://github.com/1WorldCapture/grok2api-mcp.git
cd grok2api-mcp
npm install
npm run build

Configuration

Required Environment Variables

Variable	Description
GROK_BASE_URL	Grok API base URL (e.g., https://api.x.ai)
GROK_API_TOKEN	Your Grok API authentication token

Optional Environment Variables

Variable	Default	Description
GROK_REQUEST_TIMEOUT_MS	120000	Global request timeout (ms)
GROK_X_SEARCH_TIMEOUT_MS	(global)	Timeout for x_search tool
GROK_GENERAL_SEARCH_TIMEOUT_MS	(global)	Timeout for general_search tool
GROK_IMAGE_TIMEOUT_MS	(global)	Timeout for image_generation tool
GROK_VIDEO_TIMEOUT_MS	(global)	Timeout for video_generation tool
GROK_SEARCH_MODEL	grok-4.20-beta	Model for search tools
GROK_IMAGE_MODEL	grok-imagine-1.0	Model for image generation
GROK_VIDEO_MODEL	grok-imagine-1.0-video	Model for video generation

Base URL Notes

The GROK_BASE_URL supports the following formats:

• https://api.example.com
• https://api.example.com/v1
• https://api.example.com/proxy
• https://api.example.com/proxy/v1

The server automatically handles /v1 path normalization to avoid duplicate path segments.

Usage

Running the Server

GROK_BASE_URL=https://api.x.ai GROK_API_TOKEN=your-token npx grok2api-mcp

Development Mode

npm run dev

Integration with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok2api-mcp"],
      "env": {
        "GROK_BASE_URL": "https://api.x.ai",
        "GROK_API_TOKEN": "your-api-token"
      }
    }
  }
}

Or with global installation:

{
  "mcpServers": {
    "grok": {
      "command": "grok2api-mcp",
      "env": {
        "GROK_BASE_URL": "https://api.x.ai",
        "GROK_API_TOKEN": "your-api-token"
      }
    }
  }
}

MCP Tools

1. x_search

Search and summarize X (Twitter) content.

• Model: grok-4.20-beta (default)
• Endpoint: POST /v1/chat/completions
• Stream: disabled (stream=false)

2. general_search

Perform general web search and summarization.

• Model: grok-4.20-beta (default)
• Endpoint: POST /v1/chat/completions
• Stream: disabled (stream=false)

3. image_generation

Generate images using Grok's image generation API.

• Model: grok-imagine-1.0 (default)
• Endpoint: POST /v1/images/generations
• Stream: disabled (stream=false)

4. video_generation

Generate videos using Grok's video generation API.

• Model: grok-imagine-1.0-video (default)
• Endpoint: POST /v1/chat/completions
• Stream: disabled (stream=false)

Project Structure

grok2api-mcp/
├── src/
│   ├── index.ts        # Main entry point - MCP server setup
│   ├── config.ts       # Environment variable loading and validation
│   ├── tools.ts        # MCP tool definitions and handlers
│   ├── grokClient.ts   # Grok API client wrapper
│   ├── httpClient.ts   # HTTP client with timeout/abort handling
│   ├── errors.ts       # Error types and normalization
│   ├── logger.ts       # Simple stderr logger
│   └── utils.ts        # Utility functions
├── dist/               # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Architecture

MCP Client (stdio)
        │
        ▼
┌─────────────────────────────────────────┐
│  index.ts - MCP Server                  │
│  - ListToolsRequestSchema handler       │
│  - CallToolRequestSchema handler        │
└─────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│  tools.ts - Tool Definitions            │
│  - Zod schema validation                │
│  - x_search, general_search, etc.       │
└─────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│  grokClient.ts - Grok API Client        │
│  - chatCompletions()                    │
│  - imageGenerations()                   │
└─────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│  httpClient.ts - HTTP Client            │
│  - Bearer token auth                    │
│  - Timeout & AbortController            │
│  - URL path normalization               │
└─────────────────────────────────────────┘

Error Handling

• Parameter Validation: All tool arguments are validated with Zod schemas
• Unified HTTP Client: Single client handles timeouts, abort signals, and error normalization
• Startup Validation: Required environment variables are checked at startup
• Rich Error Context: Errors include timeout thresholds, URLs, elapsed time, and hints
• SSE Detection: Explicit error if server returns SSE instead of JSON

Development

Scripts

Command	Description
npm run clean	Remove dist directory
npm run build	Clean and compile TypeScript
npm run dev	Development mode with hot reload
npm start	Run compiled server

Build

npm run build

Dependencies

• @modelcontextprotocol/sdk - Official MCP SDK
• zod - Runtime type validation

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.