README_EN.md

1. Overview

Grok Search MCP is an MCP server built on FastMCP, featuring a dual-engine architecture: Grok handles AI-driven intelligent search, while Tavily handles high-fidelity web content extraction and site mapping. Together they provide complete real-time web access for LLM clients such as Claude Code and Cherry Studio.

Claude --MCP--> Grok Search Server
                  ├─ web_search  ---> Grok API (AI Search)
                  ├─ web_fetch   ---> Tavily Extract (Content Extraction)
                  └─ web_map     ---> Tavily Map (Site Mapping)

Features

• Dual Engine: Grok search + Tavily extraction/mapping, complementary collaboration
• OpenAI-compatible interface, supports any Grok mirror endpoint
• Automatic time injection (detects time-related queries, injects local time context)
• One-click disable Claude Code's built-in WebSearch/WebFetch, force routing to this tool
• Smart retry (Retry-After header parsing + exponential backoff)
• Parent process monitoring (auto-detects parent process exit on Windows, prevents zombie processes)

Demo

Using cherry studio with this MCP configured, here's how claude-opus-4.6 leverages this project for external knowledge retrieval, reducing hallucination rates.

As shown above, for a fair experiment, we enabled Claude's built-in search tools, yet Opus 4.6 still relied on its internal knowledge without consulting FastAPI's official documentation for the latest examples.

As shown above, with grok-search MCP enabled under the same experimental conditions, Opus 4.6 proactively made multiple search calls to retrieve official documentation, producing more reliable answers.

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"

One-Click Install

If you have previously installed this project, remove the old MCP first:

claude mcp remove grok-search

Replace the environment variables in the following command with your own values. The Grok endpoint must be OpenAI-compatible; Tavily is optional — web_fetch and web_map will be unavailable without it.

GuDa Users (Recommended)

GuDa users only need to set GUDA_API_KEY to access all services — API URLs are automatically derived:

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

To use your own API endpoints, 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"
  }
}'

You can also configure additional environment variables in the env field:

Note: When GUDA_API_KEY is set, all GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_* variables become optional as they are auto-derived from GUDA_BASE_URL. Explicitly set variables take higher priority.

Verify Installation

claude mcp list

After confirming a successful connection, we highly recommend typing the following in a Claude conversation:

Call grok-search toggle_builtin_tools to disable Claude Code's built-in WebSearch and WebFetch tools

This will automatically modify the project-level .claude/settings.json permissions.deny, disabling Claude Code's built-in WebSearch and WebFetch, forcing Claude Code to use this project for searches!

3. MCP Tools

4. FAQ

License

MIT License