Skip to main content
Glama

This is an image

English | 简体中文

Grok-with-Tavily MCP, providing more complete network access for Claude Code

License: MIT Python 3.10+ FastMCP

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.

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

❌

-

GuDa API key (automatically derives URLs and keys for all services once configured)

GUDA_BASE_URL

❌

https://code.guda.studio

GuDa service base address

GROK_API_URL

❌

{GUDA_BASE_URL}/grok/v1

Grok API address (OpenAI-compatible format); overrides the GuDa-derived value when explicitly set

GROK_API_KEY

❌

{GUDA_API_KEY}

Grok API key; overrides the GuDa-derived value when explicitly set

GROK_MODEL

❌

grok-4.20-beta

Default model (takes precedence over ~/.config/grok-search/config.json when set)

TAVILY_API_KEY

❌

{GUDA_API_KEY}

Tavily API key (used for web_fetch / web_map)

TAVILY_API_URL

❌

{GUDA_BASE_URL}/tavily

Tavily API address

TAVILY_ENABLED

❌

true

Whether to enable Tavily

FIRECRAWL_API_KEY

❌

{GUDA_API_KEY}

Firecrawl API key (fallback when Tavily fails)

FIRECRAWL_API_URL

❌

{GUDA_BASE_URL}/firecrawl

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 number of retries

GROK_RETRY_MULTIPLIER

❌

1

Retry backoff multiplier

GROK_RETRY_MAX_WAIT

❌

10

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

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

query

string

✅

-

Search query

platform

string

❌

""

Focus platform (e.g. "Twitter", "GitHub, Reddit")

model

string

❌

null

Grok model ID specified per call

extra_sources

int

❌

0

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

Parameter

Type

Required

Description

session_id

string

✅

session_id returned by web_search

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.

Parameter

Type

Required

Description

url

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

url

string

✅

-

Starting URL

instructions

string

❌

""

Natural language filter instructions

max_depth

int

❌

1

Maximum traversal depth (1-5)

max_breadth

int

❌

20

Maximum links tracked per page (1-500)

limit

int

❌

50

Total link processing cap (1-500)

timeout

int

❌

150

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

model

string

✅

Model ID (e.g. "grok-4-fast", "grok-2-latest")

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

action

string

❌

"status"

"on" disables official tools / "off" enables official tools / "status" shows status

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!

Star History Chart

Available Tools

13 tools
get_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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers