Prerequisites Before installing, ensure you have:
Step 1: Obtain xAI API key
Visit xAI Developer Portal
Generate API key
In the API Keys section, click “Generate New API Key”.
Copy your key
Copy the API key (format: xai-...) and store it securely. You’ll need it for configuration.
Your API key is sensitive. Never share it publicly or commit it to version control.
Step 2: Install the server Install globally for system-wide access: git clone https://github.com/stat-guy/grok-search-mcp.git cd grok-search-mcp npm install -g .
This makes the grok-search-mcp command available globally. Use NPX to run without installing: NPX will automatically download and run the latest version. Clone and run locally for development: git clone https://github.com/stat-guy/grok-search-mcp.git cd grok-search-mcp npm install node index.js
Step 3: Verify installation Test that the installation worked:
npx grok-search-mcp --help
Expected output: Grok Search MCP Server v1.0.0 USAGE: grok-search-mcp [options] OPTIONS: --help, -h Show this help message DESCRIPTION: MCP server providing comprehensive web search capabilities using xAI's Grok API. Supports basic search results and comprehensive analysis with timelines, quotes, and multiple perspectives. ENVIRONMENT VARIABLES: XAI_API_KEY Required: Your xAI API key from https://console.x.ai/ GROK_TIMEOUT Optional: Request timeout in ms (default: 30000) GROK_MAX_RETRIES Optional: Max retry attempts (default: 3)
If you see this help message, your installation is successful!
Locate configuration file The configuration file is at: ~ /Library/Application Support/Claude/claude_desktop_config.json
Edit configuration Open the file in your editor: open -e ~/Library/Application \ Support/Claude/claude_desktop_config.json
Add server configuration Add the Grok Search server to your configuration: { "mcpServers" : { "grok-search" : { "command" : "npx" , "args" : [ "grok-search-mcp" ], "env" : { "XAI_API_KEY" : "xai-your-actual-api-key-here" } } } }
Locate configuration file The configuration file is at: % APPDATA % \ Claude \claude_desktop_config.json
Edit configuration Open the file in Notepad: notepad % APPDATA % \ Claude \claude_desktop_config.json
Add server configuration Add the Grok Search server to your configuration: { "mcpServers" : { "grok-search" : { "command" : "npx" , "args" : [ "grok-search-mcp" ], "env" : { "XAI_API_KEY" : "xai-your-actual-api-key-here" } } } }
Locate configuration file The configuration file is at: ~ /.config/Claude/claude_desktop_config.json
Edit configuration Open the file in your editor: nano ~/.config/Claude/claude_desktop_config.json
Add server configuration Add the Grok Search server to your configuration: { "mcpServers" : { "grok-search" : { "command" : "npx" , "args" : [ "grok-search-mcp" ], "env" : { "XAI_API_KEY" : "xai-your-actual-api-key-here" } } } }
Replace xai-your-actual-api-key-here with your actual xAI API key from Step 1.
Step 5: Advanced configuration (optional) Customize server behavior with additional environment variables:
Basic configuration
Advanced configuration
Development configuration
{ "mcpServers" : { "grok-search" : { "command" : "npx" , "args" : [ "grok-search-mcp" ], "env" : { "XAI_API_KEY" : "xai-your-api-key-here" } } } }
Configuration options Variable Default Description XAI_API_KEYRequired Your xAI API key from console.x.ai GROK_TIMEOUT30000Request timeout in milliseconds GROK_MAX_RETRIES3Maximum retry attempts for failed requests
Step 6: Restart Claude Desktop
Quit Claude Desktop
Completely quit the application (not just close the window).
Restart the application
Launch Claude Desktop again.
Verify server is loaded
The Grok Search tools should now appear in your available tools.
On macOS, use Cmd+Q to fully quit Claude Desktop. On Windows, right-click the system tray icon and select Quit.
Troubleshooting
Server not appearing in Claude Desktop
Symptoms: Tools don’t show up after restartSolutions:
Verify the configuration file path is correct for your OS
Check JSON syntax with a validator
Ensure Claude Desktop was fully quit and restarted
Check that Node.js 18+ is installed: node --version
Test NPX access: npx grok-search-mcp --help
Symptoms: “API service is not healthy” errorsSolutions:
Verify your API key starts with xai-
Check for extra spaces or quotes around the key
Ensure the key is active in the xAI Developer Portal
Try regenerating your API key
Symptoms: npx: command not found or similarSolutions:
Verify Node.js is installed: node --version
Verify NPM is installed: npm --version
Update NPM: npm install -g npm@latest
Reinstall Node.js from nodejs.org
JSON configuration errors
Symptoms: Claude Desktop fails to start or shows errorsSolutions:
Validate JSON syntax with a validator
Check for missing commas or brackets
Ensure proper quote escaping
Backup and recreate the configuration file
Verification Test your installation using the health check:
{ "tool" : "health_check" , "parameters" : {} }
Expected response: { "server_healthy" : true , "api_healthy" : true , "uptime_ms" : 3600000 , "total_requests" : 0 , "error_count" : 0 , "success_rate" : "N/A" , "api_details" : { "hasApiKey" : true , "cacheSize" : 0 , "lastError" : null } }
If server_healthy and api_healthy are both true, you’re ready to start searching!
Next steps
Quickstart guide Try your first search and explore the available tools
API reference Learn about all available tools and parameters
Remember to never share your API key publicly or commit it to version control. Use environment variables for sensitive configuration.
