grok-search
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grok-search Search the web for the latest AI breakthroughs and summarize"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

English | 简体中文
Grok-with-Tavily MCP, providing more complete network access for Claude Code
This is a fork of GuDaStudio/GrokSearch (sunami-grok-search). The upstream
web_searchoutsources retrieval to the upstream gateway; when connecting directly to the officialapi.x.ai, it does not actually search, but only makes the model fabricatecitation_cardcitations, withsources_countalways being 0. This fork instead uses the nativeweb_search/x_searchtools of the xAI Responses API, reads citations structurally fromannotations[].url_citation, and exposes X search account/time filters as parameters. See SUNAMI.md for details of the changes; when deploying on a new machine, just hand the prompt in PROMPT.md to an agent. Below is the original upstream documentation.
1. Overview
Grok Search MCP is an MCP server built on FastMCP, using a dual-engine architecture: Grok handles AI-driven intelligent search, and Tavily handles high-fidelity web scraping and site mapping, each playing to its strengths to provide complete real-time network access for LLM clients such as Claude Code / Cherry Studio.
Claude ──MCP──► Grok Search Server
├─ web_search ───► Grok API(AI 搜索)
├─ web_fetch ───► Tavily Extract → Firecrawl Scrape(内容抓取,自动降级)
└─ web_map ───► Tavily Map(站点映射)Features
Dual engine: Grok search + Tavily scrape/map, complementary collaboration
Firecrawl fallback: automatically degrades to Firecrawl Scrape when Tavily extraction fails, with automatic retry on empty content
OpenAI-compatible interface, supporting any Grok mirror site
Automatic time injection (detects time-related queries and injects local time context)
One-click disable of Claude Code's official WebSearch/WebFetch, forcing routing to this tool
Intelligent retry (supports Retry-After header parsing + exponential backoff)
Parent process monitoring (automatically detects parent process exit on Windows to prevent zombie processes)
Demo
Using the configuration of this MCP in cherry studio as an example, we show how the claude-opus-4.6 model uses this project to gather external knowledge and reduce hallucination rates.
As shown above, for a fair experiment, we enabled the search tool built into the claude model, yet opus 4.6 still trusts its own internal knowledge and does not query the official FastAPI documentation to get the latest examples.
As shown above, when grok-search MCP is enabled, under the same experimental conditions, opus 4.6 proactively calls search multiple times to obtain official documentation, making answers more reliable.
Related MCP server: Web Search MCP Server
2. Installation
Prerequisites
Python 3.10+
uv (recommended Python package manager)
Claude Code
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Windows users are strongly recommended to run this project in WSL.
One-click installation
If you have installed this project before, use the following command to uninstall the old MCP.
claude mcp remove grok-searchReplace the environment variables in the following command with your own values and execute. The Grok interface must be in OpenAI-compatible format; Tavily is optional, and the web_fetch and web_map tools are unavailable when it is not configured.
GuDa users (recommended)
GuDa users only need to configure GUDA_API_KEY to enjoy the full service; all API addresses are derived automatically:
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"
}
}'Custom configuration
If you want to use your own API endpoints, you can configure each service separately:
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"
}
}'In some corporate networks or proxy environments, errors like the following may occur:
certificate verify failed self signed certificate in certificate chain
You can add --native-tls to the uvx arguments to use the system certificate store:
claude mcp add-json grok-search --scope user '{ "type": "stdio", "command": "uvx", "args": [ "--native-tls", "--from", "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily", "grok-search" ], "env": { "GUDA_API_KEY": "your-guda-api-key" } }'
In addition, you can configure more environment variables in the env field
Variable | Required | Default | Description |
| ❌ | - | GuDa API key (automatically derives URLs and keys for all services once configured) |
| ❌ |
| GuDa service base address |
| ❌ |
| Grok API address (OpenAI-compatible format); overrides the GuDa-derived value when explicitly set |
| ❌ |
| Grok API key; overrides the GuDa-derived value when explicitly set |
| ❌ |
| Default model (takes precedence over |
| ❌ |
| Tavily API key (used for web_fetch / web_map) |
| ❌ |
| Tavily API address |
| ❌ |
| Whether to enable Tavily |
| ❌ |
| Firecrawl API key (fallback when Tavily fails) |
| ❌ |
| Firecrawl API address |
| ❌ |
| Debug mode |
| ❌ |
| Log level |
| ❌ |
| Log directory |
| ❌ |
| Maximum number of retries |
| ❌ |
| Retry backoff multiplier |
| ❌ |
| Maximum retry wait in seconds |
Note: After configuring
GUDA_API_KEY,GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_*are all optional; the system automatically derives them fromGUDA_BASE_URL. Individually set variables take higher precedence.
Verify installation
claude mcp list🍟 After the connection success message is shown, we strongly recommend entering the following in the Claude conversation:
调用 grok-search toggle_builtin_tools,关闭Claude Code's built-in WebSearch and WebFetch toolsThe tool will automatically modify the permissions.deny in the project-level .claude/settings.json to disable Claude Code's official WebSearch and WebFetch in one click, forcing claude code to call this project for search!
3. MCP Tools
web_search — AI web search
Performs AI-driven web search through the Grok API. By default, it returns only Grok's answer body and returns a session_id for later retrieval of sources.
web_search output does not expand sources, only returning sources_count; sources are cached on the server by session_id and can be retrieved with get_sources.
Parameter | Type | Required | Default | Description |
| string | ✅ | - | Search query |
| string | ❌ |
| Focus platform (e.g. |
| string | ❌ |
| Grok model ID specified per call |
| int | ❌ |
| Additional source count (Tavily/Firecrawl, can be 0 to disable) |
Automatically detects time-related keywords in the query (such as "latest", "today", "recent", etc.) and injects local time context to improve the accuracy of time-sensitive searches.
Return value (structured dictionary):
session_id: session ID for this querycontent: Grok answer body (sources automatically stripped)sources_count: number of cached sources
get_sources — Get sources
Retrieves all sources for the corresponding web_search via session_id.
Parameter | Type | Required | Description |
| string | ✅ |
|
Return value (structured dictionary):
session_idsources_countsources: list of sources (each item containsurl, and may containtitle/description/provider)
web_fetch — Web content scraping
Retrieves full web page content via the Tavily Extract API and returns it in Markdown format. Automatically degrades to Firecrawl Scrape as a fallback when Tavily fails.
Parameter | Type | Required | Description |
| string | ✅ | Target web page URL |
web_map — Site structure mapping
Traverses the website structure via the Tavily Map API, discovers URLs, and generates a sitemap.
Parameter | Type | Required | Default | Description |
| string | ✅ | - | Starting URL |
| string | ❌ |
| Natural language filter instructions |
| int | ❌ |
| Maximum traversal depth (1-5) |
| int | ❌ |
| Maximum links tracked per page (1-500) |
| int | ❌ |
| Total link processing cap (1-500) |
| int | ❌ |
| Timeout in seconds (10-150) |
get_config_info — Configuration diagnostics
No parameters required. Displays all configuration status, tests the Grok API connection, and returns response time and the list of available models (API key automatically masked).
switch_model — Model switching
Parameter | Type | Required | Description |
| string | ✅ | Model ID (e.g. |
After switching, the configuration is persisted to ~/.config/grok-search/config.json and remains across sessions.
toggle_builtin_tools — Tool routing control
Parameter | Type | Required | Default | Description |
| string | ❌ |
|
|
Modifies the permissions.deny in the project-level .claude/settings.json to disable Claude Code's official WebSearch and WebFetch in one click.
search_planning — Search planning
Structured search planning scaffold (phased, multi-round), used to generate an executable search plan before performing complex searches.
4. FAQ
License
If this project is helpful to you, please give it a Star!
Available Tools
13 toolsget_config_infoA
Returns current Grok Search MCP server configuration and tests API connectivity.
**Key Features:**
- **Configuration Check:** Verifies environment variables and current settings.
- **Connection Test:** Sends request to /models endpoint to validate API access.
- **Model Discovery:** Lists all available models from the API.
**Edge Cases & Best Practices:**
- Use this tool first when debugging connection or configuration issues.
- API keys are automatically masked for security in the response.
- Connection test timeout is 10 seconds; network issues may cause delays.
Inputs: no named parameters.
get_sourcesB
When you feel confused or curious about the search response content, use the session_id returned by web_search to invoke the this tool to obtain the corresponding list of information sources.
Retrieve all cached sources for a previous web_search call.
Provide the session_id returned by web_search to get the full source list.
Inputs: session_id (required). Returns: object
plan_complexityA
Phase 2: Assess search complexity (1-3). Controls required phases: Level 1 = phases 1-3; Level 2 = phases 1-5; Level 3 = all 6.
Inputs: level (required), thought (required), session_id (required), justification (required), +4 more.
plan_executionC
Phase 6: Define execution order. parallel_groups: semicolon-separated groups of comma-separated IDs (e.g., 'sq1,sq2;sq3').
Inputs: thought (required), sequential (required), session_id (required), parallel_groups (required), +3 more.
plan_intentA
Phase 1 of search planning: Analyze user intent. Call this FIRST to create a session.
Returns session_id for subsequent phases. Required flow:
plan_intent → plan_complexity → plan_sub_query(×N) → plan_search_term(×N) → plan_tool_mapping(×N) → plan_execution
Required phases depend on complexity: Level 1 = phases 1-3; Level 2 = phases 1-5; Level 3 = all 6.
Inputs: thought (required), query_type (required), core_question (required), time_sensitivity (required), +7 more.
plan_search_termB
Phase 4: Add one search term. Call once per term; data accumulates. First call must set approach.
Inputs: term (required), round (required), purpose (required), thought (required), +5 more.
plan_sub_queryA
Phase 3: Add one sub-query. Call once per sub-query; data accumulates across calls. Set is_revision=true to replace all.
Inputs: id (required), goal (required), thought (required), boundary (required), +6 more.
plan_tool_mappingC
Phase 5: Map a sub-query to a tool. Call once per mapping; data accumulates.
Inputs: tool (required), reason (required), thought (required), session_id (required), +4 more.
switch_modelA
Switches the default Grok model used for search and fetch operations, persisting the setting.
**Key Features:**
- **Model Selection:** Change the AI model for web search and content fetching.
- **Persistent Storage:** Model preference saved to ~/.config/grok-search/config.json.
- **Immediate Effect:** New model used for all subsequent operations.
**Edge Cases & Best Practices:**
- Use get_config_info to verify available models before switching.
- Invalid model IDs may cause API errors in subsequent requests.
- Model changes persist across sessions until explicitly changed again.
Inputs: model (required).
toggle_builtin_toolsA
Toggle Claude Code's built-in WebSearch and WebFetch tools on/off.
**Key Features:**
- **Tool Control:** Enable or disable Claude Code's native web tools.
- **Project Scope:** Changes apply to current project's .claude/settings.json.
- **Status Check:** Query current state without making changes.
**Edge Cases & Best Practices:**
- Use "on" to block built-in tools when preferring this MCP server's implementation.
- Use "off" to restore Claude Code's native tools.
- Use "status" to check current configuration without modification.
Inputs: action.
web_fetchA
Fetches and extracts complete content from a URL, returning it as a structured Markdown document.
**Key Features:**
- **Full Content Extraction:** Retrieves and parses all meaningful content (text, images, links, tables, code blocks).
- **Markdown Conversion:** Converts HTML structure to well-formatted Markdown with preserved hierarchy.
- **Content Fidelity:** Maintains 100% content fidelity without summarization or modification.
**Edge Cases & Best Practices:**
- Ensure URL is complete and accessible (not behind authentication or paywalls).
- May not capture dynamically loaded content requiring JavaScript execution.
- Large pages may take longer to process; consider timeout implications.
Inputs: url (required).
web_mapA
Maps a website's structure by traversing it like a graph, discovering URLs and generating a comprehensive site map.
**Key Features:**
- **Graph Traversal:** Explores website structure starting from root URL.
- **Depth & Breadth Control:** Configure traversal limits to balance coverage and performance.
- **Instruction Filtering:** Use natural language to focus crawler on specific content types.
**Edge Cases & Best Practices:**
- Start with low max_depth (1-2) for initial exploration, increase if needed.
- Use instructions to filter for specific content (e.g., "only documentation pages").
- Large sites may hit timeout limits; adjust timeout and limit parameters accordingly.
Inputs: url (required), limit, timeout, max_depth, +2 more. Returns: result
web_searchA
Deep web + X (Twitter) search. Grok runs the retrieval; you read the sources.
In native mode this calls xAI's Responses API with the real web_search and
x_search tools, so citations come back as structured API data rather than
text the model wrote. X search is the reason to reach for this tool: live
community reaction, developer chatter, and breaking discussion that does not
exist in a search index yet.
Use x_handles to pin the search to specific accounts, and from_date/to_date
to bound it in time (both ISO8601, e.g. 2026-08-01).
Returns:
- session_id: string (pass to get_sources for the full source list)
- content: string (answer only)
- sources_count: int (0 means retrieval genuinely returned nothing -- treat
any factual claim in content as unverified)
- search_mode: "native" | "legacy" (which path actually served the request)
Inputs: query (required), mode, model, to_date, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
The core search/fetch tools (web_search, get_sources, web_fetch, web_map) are clearly distinct. The six planning tools (plan_*) are sequential phases with explicit ordering, so though they share a prefix, each has a unique purpose. Minor risk of confusion between plan_sub_query and plan_search_term, but descriptions clarify the difference.
All tools use snake_case and follow a clear verb_noun pattern (e.g., web_search, get_sources, switch_model, plan_intent). The planning tools uniformly start with 'plan_' and the rest use action verbs. Consistent naming across the entire set.
13 tools is a moderate count. The core search operations (search, fetch, map, sources) justify their presence, and the 6 planning tools form a structured workflow. While it feels slightly heavy for a search server, every tool has a defined role and the count is not excessive.
The tool set covers the search lifecycle: planning (plan_*), executing search (web_search), retrieving sources (get_sources), fetching content (web_fetch), and site exploration (web_map). Configuration and integration tools (get_config_info, switch_model, toggle_builtin_tools) round out the surface. Minor gap: no explicit tool to clear or manage cached sessions, but that is not a core search operation.
Maintenance
Related MCP Connectors
Search the web, fetch any URL and map a site as clean, LLM-ready Markdown.
Web search, URL content extraction to Markdown, site mapping, and recursive web crawler.
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides web search and content extraction for AI agents.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to perform web searches, extract webpage content, and conduct end-to-end search-and-extract operations using multiple search providers and content extraction methods.-
- AlicenseAqualityBmaintenanceEnables AI agents to perform web searches, fetch and extract page content, and crawl sites with caching, rate limiting, and robots.txt compliance, all without needing API keys.171,855 PyPI2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to perform live web searches with ranked results and extracted page passages, plus clean markdown extraction of any URL.MIT