Enhanced Grok Search MCP Server

Enhanced Grok Search MCP Server

A robust MCP (Model Context Protocol) server that provides comprehensive web search and analysis capabilities using xAI's Grok API.

Features

🔍 **Search Capabilities**

• Web Search: Search general web content using Grok's AI-powered search
• News Search: Search for recent news and current events with timeline analysis
• Twitter/X Search: Search social media posts with sentiment analysis
• Date Range Filtering: Search within specific time periods

📊 **Analysis Modes**

• Basic Mode: Traditional search results with titles, snippets, and URLs
• Comprehensive Mode: Rich analysis including:
  • Detailed timelines of events
  • Direct quotes with full attribution
  • Multiple perspectives and viewpoints
  • Historical context and implications
  • Fact verification status
  • Key findings categorization

🛡️ **Reliability Features**

• Retry Logic: Automatic retry with exponential backoff for failed requests
• Request Timeouts: Configurable timeouts to prevent hanging
• Graceful Error Handling: Comprehensive error responses with detailed context
• Health Monitoring: Built-in health checks and performance metrics
• Caching: Intelligent caching for comprehensive analyses
• Input Validation: Enhanced sanitization and validation of all inputs

🔧 **Technical Features**

• NPX Compatible: Easy installation and usage via NPX
• MCP Protocol: Full compatibility with MCP clients like Claude Desktop
• Structured Logging: Comprehensive logging for debugging and monitoring
• Performance Metrics: Request tracking and success rate monitoring

Installation

Simple 3-Step Process

git clone https://github.com/stat-guy/grok-search-mcp.git
cd grok-search-mcp
npm install -g .

Verify Installation

Test that the installation worked:

npx grok-search-mcp --help

Success indicator: If you see Grok Search MCP Server running on stdio, your installation is ready!

Alternative: NPX Usage

npx grok-search-mcp

Setup

1. Get Your xAI API Key

1. Visit the xAI Developer Portal
2. Create an account or sign in
3. Generate your API key
4. Copy the API key for the next step

2. Configure Environment Variable

Set your xAI API key as an environment variable:

export XAI_API_KEY="your-api-key-here"

Or create a .env file in your project:

XAI_API_KEY=your-api-key-here

3. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

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

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

Available Tools

`grok_search`

General-purpose search tool with configurable search types and analysis modes.

Parameters:

• query (required): The search query
• search_type (optional): "web", "news", or "general" (default: "web")
• analysis_mode (optional): "basic" or "comprehensive" (default: "basic")
• max_results (optional): Maximum number of results (1-20, default: 10)
• from_date (optional): Start date in YYYY-MM-DD format
• to_date (optional): End date in YYYY-MM-DD format

Basic Mode Example:

{
  "query": "latest AI developments",
  "search_type": "news",
  "max_results": 5
}

Comprehensive Mode Example:

{
  "query": "US Iran conflict 2025",
  "search_type": "news",
  "analysis_mode": "comprehensive",
  "max_results": 10,
  "from_date": "2025-06-20",
  "to_date": "2025-06-24"
}

`grok_web_search`

Search general web content with comprehensive analysis support.

Parameters:

• query (required): The web search query
• analysis_mode (optional): "basic" or "comprehensive" (default: "basic")
• max_results (optional): Maximum number of results (1-20, default: 10)
• from_date (optional): Start date in YYYY-MM-DD format
• to_date (optional): End date in YYYY-MM-DD format

`grok_news_search`

Search for recent news with comprehensive timeline and context analysis.

Parameters:

• query (required): The news search query
• analysis_mode (optional): "basic" or "comprehensive" (default: "basic")
• max_results (optional): Maximum number of results (1-20, default: 10)
• from_date (optional): Start date in YYYY-MM-DD format
• to_date (optional): End date in YYYY-MM-DD format

`grok_twitter`

Search Twitter/X posts with social media analysis.

Parameters:

• query (required): The search query for tweets
• handles (optional): Array of Twitter handles to filter by (without @ symbol)
• analysis_mode (optional): "basic" or "comprehensive" (default: "basic")
• max_results (optional): Maximum number of results (1-20, default: 10)
• from_date (optional): Start d