Grok Search

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

- 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

- 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

- 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

- 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

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

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

Set your xAI API key as an environment variable:

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

Add the server to your Claude Desktop configuration file:

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

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

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

- 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

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

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

Search general web content with comprehensive analysis support.

- 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

Search for recent news with comprehensive timeline and context analysis.

- 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

Search Twitter/X posts with social media analysis.

- 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 date in YYYY-MM-DD format
- to_date(optional): End date in YYYY-MM-DD format

Check server health and API connectivity status.

{ "query": "search query", "analysis_mode": "basic", "results": [ { "title": "Result Title", "snippet": "Brief description or excerpt", "url": "https://example.com", "source": "source-name", "published_date": "2025-06-24", "author": "Author Name", "citation_url": "https://example.com", "citation_metadata": { "domain": "example.com", "is_secure": true } } ], "citations": ["https://example.com"], "summary": "Brief overview of findings", "total_results": 5, "search_time": "2025-06-24T12:00:00.000Z", "source": "grok-live-search" }

{ "query": "search query", "analysis_mode": "comprehensive", "comprehensive_analysis": "Detailed analysis with context and implications...", "key_findings": [ { "category": "main_story", "title": "Primary Development", "content": "Detailed explanation with specifics", "sources": ["https://source1.com", "https://source2.com"], "confidence": "high" } ], "timeline": [ { "date": "2025-06-21", "event": "Initial event occurred", "source": "News Source", "significance": "This marked the beginning of..." } ], "direct_quotes": [ { "quote": "This is an exact quote from the source", "speaker": "Official Name", "context": "During a press conference on Monday", "source_url": "https://source.com", "significance": "This statement clarifies the position..." } ], "related_context": "Historical background and connections...", "multiple_perspectives": [ { "viewpoint": "Supporters", "content": "Analysis from this perspective", "sources": ["https://supporting-source.com"], "reasoning": "This group supports because..." } ], "implications": { "short_term": "Immediate consequences include...", "long_term": "Potential long-term impacts are...", "stakeholders_affected": ["Group 1", "Group 2"] }, "verification_status": { "confirmed_facts": ["Verified information"], "unconfirmed_claims": ["Unverified claims"], "contradictory_information": ["Conflicting reports"] }, "raw_results": [ { "title": "Source Article", "snippet": "Brief description", "url": "https://example.com", "relevance_score": 9 } ], "summary": "Executive summary of the entire analysis", "total_results": 10, "search_time": "2025-06-24T12:00:00.000Z", "source": "grok-comprehensive-analysis" }

- XAI_API_KEY(required): Your xAI API key
- GROK_TIMEOUT(optional): Request timeout in milliseconds (default: 30000)
- GROK_MAX_RETRIES(optional): Maximum retry attempts (default: 3)

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

The server includes comprehensive error handling with standardized error responses:

- Invalid API Key: Graceful degradation with clear error messages
- Empty Query: Enhanced validation with detailed feedback
- API Rate Limits: Automatic retry with exponential backoff
- Network Issues: Connection error handling with retry logic
- Timeout Issues: Configurable timeouts with clear error reporting
- JSON Parsing: Multiple parsing strategies with fallback handling

{ "error": "Detailed error message", "status": "failed", "query": "original query", "search_type": "web", "analysis_mode": "basic", "timestamp": "2025-06-24T12:00:00.000Z", "request_id": "req_1234567890_abc123" }

- Comprehensive Analysis Caching: Intelligent caching for expensive comprehensive analyses
- TTL Management: Configurable cache expiration (default: 30 minutes)
- Memory Management: Automatic cache size limits to prevent memory issues

- Health Checks: Built-in health monitoring with detailed status reporting
- Performance Metrics: Request tracking, success rates, and timing analysis
- Structured Logging: JSON-formatted logs for easy parsing and monitoring

- Retry Logic: Exponential backoff for transient failures
- Circuit Breaking: Graceful degradation when API is unavailable
- Input Sanitization: Comprehensive input validation and cleaning
- Error Recovery: Multiple JSON parsing strategies for robust response handling
-

"API service is not available"

- Check if XAI_API_KEY is set correctly
- Verify your API key is valid and active
- Use the health_check tool to diagnose API connectivity

- Increase GROK_TIMEOUT environment variable
- Check your internet connection
- Consider using basic mode for faster responses

- Queries are limited to 1000 characters
- Break down complex queries into smaller parts

Empty or poor results in comprehensive mode

- Try different query phrasings
- Use basic mode for simple searches
- Check if the topic has sufficient recent coverage

Use the health_check tool to get detailed status:

{ "tool": "health_check" }

{ "server_healthy": true, "api_healthy": true, "uptime_ms": 3600000, "total_requests": 150, "error_count": 3, "success_rate": "98.00%", "api_details": { "hasApiKey": true, "cacheSize": 12 } }

The server provides structured logging. Monitor stderr output for detailed logs:

Run the test suite to verify functionality:

# With API key XAI_API_KEY=your-key npm test # Basic functionality test (may skip API calls) npm test

{ "query": "latest technology news", "search_type": "news", "max_results": 5 }

{ "query": "climate change policy 2025", "analysis_mode": "comprehensive", "search_type": "news", "from_date": "2025-01-01", "max_results": 15 }

{ "query": "AI developments", "handles": ["elonmusk", "OpenAI", "AnthropicAI"], "analysis_mode": "comprehensive", "max_results": 10 }

{ "query": "quantum computing breakthroughs", "search_type": "web", "from_date": "2025-06-01", "to_date": "2025-06-24", "max_results": 8 }

- Rate limits depend on your xAI API plan
- Monitor usage through the xAI Developer Portal
- Comprehensive mode uses more tokens than basic mode
- Caching helps reduce API usage for repeated queries

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

For issues and feature requests, please create an issue in the repository.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Update documentation
- Submit a pull request

- ✅ Added comprehensive analysis mode with rich context
- ✅ Implemented timeline extraction and direct quotes
- ✅ Added multiple perspectives analysis
- ✅ Enhanced error handling with retry logic
- ✅ Added intelligent caching for comprehensive analyses
- ✅ Implemented health monitoring and performance metrics
- ✅ Added structured logging system
- ✅ Enhanced input validation and sanitization
- ✅ Added configurable timeouts and retry settings
- ✅ Improved JSON parsing with multiple fallback strategies

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

Access Jina AI's Search Foundation APIs for web search, news search, and more, tailored for LLMs.

Automated fact-checking of news headlines using web search and Google Gemini AI.

Reddit, Twitter, Google Trends, LinkedIn, Medium, Dev.to & News MCP server that uses your Chrome login session. 13 tools, fully local, pip install.

A connector for the Perplexity API to enable web search within the MCP ecosystem.

Objective-driven deep research paid per request via MPP - free daily quick search (news/arXiv), quote-first paid cloud-browser research with cross-source reports. MCP Streamable HTTP, no API key.

About Free multi-engine MCP search server — 8 free engines (DDG, Sogou, Bing, Baidu, Wikipedia, Startpage, Yandex, Mojeek), waterfall progressive search, multi-source verification, content enrichment, news search, language auto-detection, rate limit exposure. Zero API keys needed. Self-hostable.

Structural AI Search Readiness MCP. Audit, dry-run fixes, rescore, doctor. No LLM rankings.

Hosted MCP server for the APITube News API: search articles from 500,000+ sources in 60+ languages, filtered by sentiment, entities, topics and source quality.

A search engine for AI applications, providing world knowledge from web pages and various content sources like weather, news, and images.