grok-search

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_search outsources retrieval to the upstream gateway; when connecting directly to the official api.x.ai, it does not actually search, but only makes the model fabricate citation_card citations, with sources_count always being 0. This fork instead uses the native web_search / x_search tools of the xAI Responses API, reads citations structurally from annotations[].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.

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-search

Replace 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

Note: After configuring GUDA_API_KEY, GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_* are all optional; the system automatically derives them from GUDA_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 tools

The 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.

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 query

• content: 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.

Return value (structured dictionary):

• session_id

• sources_count

• sources: list of sources (each item contains url, and may contain title/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.

web_map — Site structure mapping

Traverses the website structure via the Tavily Map API, discovers URLs, and generates a sitemap.

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

After switching, the configuration is persisted to ~/.config/grok-search/config.json and remains across sessions.

toggle_builtin_tools — Tool routing control

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

MIT License

If this project is helpful to you, please give it a Star!