repository·main·Indexed 21 days ago
https://github.com/gudastudio/groksearchAn MCP server built on FastMCP that provides LLM clients, such as Claude Code and Cherry Studio, with advanced web access. It uses a dual-engine architecture combining Grok for AI-driven search with Tavily and Firecrawl for high-fidelity web scraping and site mapping. Key tools include web_search for AI queries, get_sources for metadata retrieval, web_fetch for Markdown content extraction, and web_map for website structure traversal.
After installation, verify that the MCP server is correctly connected using the Claude CLI:
claude mcp listTo test the configuration within a Claude conversation, you can ask:
Show grok-search configuration info
To install the Grok Search MCP server, you must have Python 3.10+, uv installed, and Claude Code.
First, if you have an older version installed, remove it using:
claude mcp remove grok-searchThen, add the MCP server using the claude mcp add-json command. You must replace the placeholder environment variables with your actual credentials. The Grok API must be in an OpenAI-compatible format. Tavily configuration is optional; if omitted, web_fetch and web_map tools will be unavailable.
If you encounter SSL/certificate verification errors in enterprise or proxy environments, add the --native-tls flag to the args array in the JSON configuration.
claude mcp add-json grok-search --scope user '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
"grok-search"
],
"env": {
"GROK_API_URL": "https://your-api-endpoint.com/v1",
"GROK_API_KEY": "your-grok-api-key",
"TAVILY_API_KEY": "tvly-your-tavily-key",
"TAVILY_API_URL": "https://api.tavily.com"
}
}'To ensure Claude Code uses the Grok Search MCP instead of its own built-in web tools, you can use the toggle_builtin_tools tool. This modifies the project-level .claude/settings.json permissions.deny settings.
In a Claude conversation, type:
Call grok-search toggle_builtin_tools to disable Claude Code's built-in WebSearch and WebFetch tools
To install Grok Search MCP, use the claude mcp add-json command. You can choose between a simplified setup using a GuDa API key or a custom configuration using your own API endpoints.
Prerequisites:
Note for Windows users: It is strongly recommended to run this project in WSL.
#### GuDa Users (Recommended)
```bash
claude mcp add-json grok-search --scope user '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
"grok-search"
],
"env": {
"GUDA_API_KEY": "your-guda-api-key"
}
}'claude mcp add-json grok-search --scope user '{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
"grok-search"
],
"env": {
"GROK_API_URL": "https://your-api-endpoint.com/v1",
"GROK_API_KEY": "your-grok-api-key",
"TAVILY_API_KEY": "tvly-your-tavily-key",
"TAVILY_API_URL": "https://api.tavily.com"
}
}'The following environment variables can be used to configure the Grok Search MCP server:
| Variable | Required | Default | Description |
|---|---|---|---|
GROK_API_URL | ✅ | - | Grok API address (OpenAI compatible format) |
GROK_API_KEY | ✅ | - | Grok API key |
GROK_MODEL | ❌ | grok-4-fast | Default model (overrides ~/.config/grok-search/config.json) |
TAVILY_API_KEY | ❌ | - | Tavily API key (used for web_fetch / web_map) |
TAVILY_API_URL | ❌ | https://api.tavily.com | Tavily API address |
TAVILY_ENABLED | ❌ | true | Whether to enable Tavily |
FIRECRAWL_API_KEY | ❌ | - | Firecrawl API key (fallback for Tavily) |
FIRECRAWL_API_URL | ❌ | https://api.firecrawl.dev/v2 | Firecrawl API address |
GROK_DEBUG | ❌ | false | Debug mode |
GROK_LOG_LEVEL | ❌ | INFO | Log level |
GROK_LOG_DIR | ❌ | logs | Log directory |
GROK_RETRY_MAX_ATTEMPTS | ❌ | 3 | Maximum retry attempts |
GROK_RETRY_MULTIPLIER | ❌ | 1 | Retry backoff multiplier |
GROK_RETRY_MAX_WAIT | ❌ | 10 | Maximum retry wait in seconds |
Grok Search implements a multi-phase planning engine to handle complex queries. Instead of a single search, it breaks down intent into a structured execution plan.
The Required Workflow:
plan_intent: Analyze the core question and create a session_id.plan_complexity: Assess if the search is Level 1, 2, or 3 complexity.plan_sub_query: Decompose the main question into specific sub-goals.plan_search_term: Define specific search queries for each sub-query.plan_tool_mapping: Decide which tool (web_search, web_fetch, or web_map) to use for each sub-query.plan_execution: Define the order (parallel or sequential) in which tools are called.This structured approach ensures high-quality, deep research by managing dependencies and execution strategies.
To use GrokSearch as a Model Context Protocol (MCP) server in Claude Desktop, you must configure the required environment variables. Use the following command to add the server to your Claude configuration. Replace your-api-url and your-api-key with your actual Grok API credentials.
Note: The GROK_API_URL and GROK_API_KEY environment variables are mandatory for the server to function.
In addition to search and extraction, the server provides several utility tools:
get_config_info: Displays configuration status, tests Grok API connection, and lists available models.switch_model: Changes the active Grok model. Settings are persisted to ~/.config/grok-search/config.json.toggle_builtin_tools: Controls whether Claude Code's native web tools are disabled or enabled via action ("on", "off", or "status").search_planning: Generates a structured multi-phase plan for complex searches.To prevent Claude Code from using its own built-in WebSearch and WebFetch tools (which might be less effective than Grok Search), use toggle_builtin_tools. This tool modifies the project-level .claude/settings.json file's permissions.deny section.
Parameters:
action (string, Optional):"on": Disable official Claude tools."off": Enable official Claude tools."status": Check current status. Default is "status".To view the specific URLs and metadata used in a previous search, use the get_sources tool. This requires the session_id returned by the web_search tool.
Parameters:
session_id (string, Required): The session ID from the web_search response.The web_map tool uses the Tavily Map API to traverse a website's structure and generate a sitemap of discovered URLs.
Parameters:
url (string, Required): The starting URL.instructions (string, Optional): Natural language instructions to filter results.max_depth (int, Optional): Maximum traversal depth (1-5). Default is 1.max_breadth (int, Optional): Maximum links to follow per page (1-500). Default is 20.limit (int, Optional): Total limit of links to process (1-500). Default is 50.timeout (int, Optional): Timeout in seconds (10-150). Default is 150.The web_fetch tool retrieves the full content of a webpage in Markdown format. It uses the Tavily Extract API by default. If Tavily fails, it automatically falls back to Firecrawl Scrape.
Parameters:
url (string, Required): The target webpage URL.