grok-mcp 0.2.0

MCP server for Grok X.com search integration using xAI API

Grok X.com Search MCP Server

A Model Context Protocol (MCP) server that integrates xAI's Grok API for X.com search functionality. This server enables Claude Desktop and Claude Code users to search and analyze X/Twitter content with real-time data access.

Features

• Real-time X.com Search: Search posts, users, conversation threads, and trending topics
• Advanced Analysis: Basic and comprehensive analysis modes with sentiment analysis
• Robust Error Handling: Retry logic, rate limiting, and graceful degradation
• Claude Integration: Works with both Claude Desktop and Claude Code via MCP protocol
• Comprehensive Filtering: Date ranges, user handles, engagement metrics

Quick Start

Prerequisites

• Python 3.12+
• xAI API key from console.x.ai

Install from PyPI

# Using uvx (recommended)
uvx grok-mcp

# Or using pip
pip install grok-mcp

Configuration

Claude Code

Add to your Claude Code MCP settings:

Project scope (.mcp.json in your project root):

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": ["grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

User scope (~/.claude.json):

claude mcp add grok-search -s user -- uvx grok-mcp

Then edit ~/.claude.json to add the env variable:

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": ["grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": ["grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

Restart Claude Desktop after adding the configuration.

Available Tools

search_posts

Search X.com posts with advanced filtering and analysis options.

Parameter	Required	Description
query	Yes	Search query for X.com posts
max_results	No	Maximum results (1-100, default: 20)
handles	No	Filter by user handles (without @)
start_date	No	Start date (YYYY-MM-DD)
end_date	No	End date (YYYY-MM-DD)
analysis_mode	No	"basic" or "comprehensive"

search_users

Search for X.com users and profiles.

Parameter	Required	Description
query	Yes	Search query for users
max_results	No	Maximum results (1-50, default: 20)

search_threads

Search X.com conversation threads and replies.

Parameter	Required	Description
query	Yes	Search query for threads
max_results	No	Maximum threads (1-20, default: 10)

get_trends

Get trending topics and hashtags on X.com.

Parameter	Required	Description
location	No	Location (e.g., "United States", "Global")
max_results	No	Maximum trends (1-50, default: 20)

health_check

Check the health and status of the Grok API connection.

Development

Setup for Development

git clone https://github.com/guzus/grok-mcp.git
cd grok-mcp
uv sync --dev

Run Tests

uv run pytest
uv run pytest --cov=src/grok_mcp

Validate Configuration

uv run python scripts/validate_config.py

Architecture

grok-mcp/
├── src/grok_mcp/
│   ├── server.py           # Main MCP server
│   ├── config.py           # Configuration management
│   ├── grok_client.py      # Grok API client with retry/rate limiting
│   ├── search_tools.py     # Search tool implementations
│   ├── response_formatter.py  # Response formatting
│   └── exceptions.py       # Custom exceptions
├── tests/                  # Test suite
└── scripts/               # Utility scripts

Publishing

This server is available on:

• PyPI: pip install grok-mcp or uvx grok-mcp
• MCP Registry: Listed as io.github.guzus/grok-mcp
• Smithery: Available at smithery.ai

Publish to PyPI

uv build
uv publish

Publish to MCP Registry

mcp-publisher login github
mcp-publisher publish

Troubleshooting

"API key not configured"

• Ensure XAI_API_KEY is set in your MCP configuration
• Verify the API key is valid at console.x.ai

"Tool not found"

• Restart Claude Desktop/Code after configuration changes
• Check that uvx or pip is available in your PATH

Rate limit errors

• The server implements automatic retry with exponential backoff
• Check your xAI API usage limits

License

MIT License - see LICENSE for details.

Links

• xAI API Documentation
• Model Context Protocol
• MCP Registry
• Claude Code
• Claude Desktop