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
- Visit the xAI Developer Portal
- Create an account or sign in
- Generate your API key
- 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 querysearch_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 formatto_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 queryanalysis_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 formatto_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 queryanalysis_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 formatto_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 tweetshandles(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 formatto_date(optional): End date in YYYY-MM-DD format
health_check
Check server health and API connectivity status.
Parameters: None
Response Formats
Basic Mode Response
{
"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"
}
Comprehensive Mode Response
{
"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"
}
Configuration
Environment Variables
XAI_API_KEY(required): Your xAI API keyGROK_TIMEOUT(optional): Request timeout in milliseconds (default: 30000)GROK_MAX_RETRIES(optional): Maximum retry attempts (default: 3)
Claude Desktop Configuration Example
{
"mcpServers": {
"grok-search": {
"command": "npx",
"args": ["grok-search-mcp"],
"env": {
"XAI_API_KEY": "your-api-key-here",
"GROK_TIMEOUT": "45000",
"GROK_MAX_RETRIES": "5"
}
}
}
}
Error Handling
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 Response Format
{
"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"
}
Performance Features
Caching
- 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
Monitoring
- 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
Reliability
- 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
Troubleshooting
Common Issues
-
"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
-
"Request timeout after Xms"
- Increase GROK_TIMEOUT environment variable
- Check your internet connection
- Consider using basic mode for faster responses
-
"Search query too long"
- 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
Health Monitoring
Use the health_check tool to get detailed status:
{
"tool": "health_check"
}
Example health response:
{
"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
}
}
Debugging
The server provides structured logging. Monitor stderr output for detailed logs:
npx grok-search-mcp 2>debug.log
Testing
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
Usage Examples
Basic News Search
{
"query": "latest technology news",
"search_type": "news",
"max_results": 5
}
Comprehensive Analysis
{
"query": "climate change policy 2025",
"analysis_mode": "comprehensive",
"search_type": "news",
"from_date": "2025-01-01",
"max_results": 15
}
Twitter Analysis with Specific Handles
{
"query": "AI developments",
"handles": ["elonmusk", "OpenAI", "AnthropicAI"],
"analysis_mode": "comprehensive",
"max_results": 10
}
Date-Filtered Web Search
{
"query": "quantum computing breakthroughs",
"search_type": "web",
"from_date": "2025-06-01",
"to_date": "2025-06-24",
"max_results": 8
}
API Limits
- 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
License
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.
Support
For issues and feature requests, please create an issue in the repository.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Update documentation
- Submit a pull request
Changelog
Version 2.0.0 (Enhanced)
- ✅ 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