GrokSearch：让Claude接入Grok实时搜索的MCP工具，双引擎+自动降级

“我们打开了 Claude 模型内置的搜索工具，然而 opus 4.6 仍然相信自己的内部常识，不查询官方文档。当打开 GrokSearch MCP 时，相同条件下，opus 4.6 主动调用多次搜索获取官方文档。"——项目 README 的对比实验

一句话定位

GrokSearch 是一个基于 FastMCP 构建的 MCP 服务器，通过双引擎架构（Grok AI 搜索 + Tavily/Firecrawl 网页抓取）为 Claude Code 提供实时网络访问能力。

说人话：让 Claude 在回答问题前主动去网上搜真实信息，而不是靠幻觉硬撑。

当前 GitHub ⭐ 1.6k，Python 3.10+，MIT 许可证。

解决什么问题

Claude Code 的 Web Search 困境

README 里有个很说明问题的对比实验：

实验设置：让 Claude Opus 4.6 回答一个需要查官方文档的问题（FastAPI 最新示例），同时打开 Claude 内置的 WebSearch 工具。

结果：Claude 仍然选择相信自己的内部常识，根本不调用搜索工具，幻觉了一个答案。

加了 GrokSearch 后：在相同条件下，Claude 主动调用多次搜索，从官方文档获取了正确答案。

这暴露了一个普遍问题：LLM 的内置搜索工具对 LLM 自己没有约束力，LLM 会在"我觉得我知道"和"我去搜一下"之间选择前者。

GrokSearch 的设计让这个问题更容易被解决：它提供了一键禁用官方工具的功能（toggle_builtin_tools），强制所有搜索请求路由到 GrokSearch。

架构设计：双引擎互补

Claude ──MCP──► Grok Search Server
                  ├─ web_search  ───► Grok API（AI 驱动的智能搜索）
                  ├─ web_fetch   ───► Tavily Extract → Firecrawl Scrape（内容抓取，自动降级）
                  └─ web_map     ───► Tavily Map（站点结构映射）

Grok：AI 驱动的搜索

web_search 通过 Grok API 执行搜索，返回 Grok 整理后的回答正文。Grok 的优势在于AI 驱动的搜索理解：它不只是返回一堆链接，而是理解查询意图后给出综合回答。

特别设计：自动时间注入。当检测到时间相关关键词（“最新"“今天"“recent"等）时，自动注入本地时间上下文，让搜索结果更具时效性。

Tavily + Firecrawl：抓取托底

web_fetch 优先使用 Tavily Extract API 获取网页内容（返回 Markdown 格式）。当 Tavily 失败时，自动降级到 Firecrawl Scrape 进行托底抓取。

这种降级设计很实用：Tavily 对某些站点的抓取可能失败，Firecrawl 作为备选保证了一定的成功率。

信源缓存机制

web_search 不直接返回信源列表，而是返回 session_id。信源缓存在服务端，通过 get_sources(session_id) 按需获取。这避免了在搜索结果中混入大量 URL 让 LLM 分心。

八个 MCP 工具

toggle_builtin_tools 的实际价值

这是 GrokSearch 最实用的功能之一。Claude Code 的官方 WebSearch/WebFetch 工具权限默认是 allow 的，LLM 可以选择不用。调用此工具后会修改项目级 .claude/settings.json 的 permissions.deny，把官方搜索工具禁用掉：

// .claude/settings.json
{
  "permissions": {
    "deny": ["web-search", "web-fetch"]  // 官方工具被禁用
  }
}

这强迫 LLM 必须通过 GrokSearch 访问网络，从而减少幻觉。

安装与配置

环境要求

• Python 3.10+
• uv（推荐的包管理器）
• Claude Code

一键安装

# 先卸载旧版（如有）
claude mcp remove grok-search

# 安装（替换环境变量）
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"
  }
}'

关键环境变量

验证安装

claude mcp list
# 应该看到 grok-search

安装成功后，在 Claude 对话中说：

调用 grok-search toggle_builtin_tools，关闭Claude Code's built-in WebSearch and WebFetch tools

一键禁用官方工具。

技术实现细节

基于 FastMCP 2.0

GrokSearch 基于 FastMCP 构建。FastMCP 是一个流行的 Python MCP 服务器框架，简化了 MCP 协议的实现。

OpenAI 兼容接口

GrokSearch 的 Grok 连接支持任意 OpenAI 兼容格式的 API 地址。这意味着：

• 可以用官方 Grok（通过兼容 OpenAI 格式的镜像站）
• 可以用任何兼容 OpenAI API 格式的 Grok 第三方提供商
• 网络配置灵活，支持企业代理和自建 API

智能重试机制

内置指数退避重试，支持解析 Retry-After HTTP 头：

# 配置重试策略
GROK_RETRY_MAX_ATTEMPTS=3      # 最大重试3次
GROK_RETRY_MULTIPLIER=1        # 退避乘数
GROK_RETRY_MAX_WAIT=10         # 最大等待10秒

Windows 父进程监控

Windows 环境下 MCP 服务器的父进程（Claude Code）退出后，服务器可能变成僵尸进程。GrokSearch 自动检测父进程退出，防止僵尸进程残留。

企业网络 SSL 问题

部分企业网络/代理环境会出现 SSL 证书验证错误。--native-tls 参数让 uvx 使用系统证书库解决：

"--native-tls",
"--from",
"git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",

适用场景

✅ 强项场景：

• 需要实时信息的 AI 编程任务：查最新文档、API 版本、第三方库用法
• 减少 LLM 幻觉：强迫 LLM 查真实网页而非凭"记忆"回答
• 复杂搜索任务：search_planning 支持分阶段多轮搜索规划
• 站点内容抓取：Tavily Extract + Firecrawl 托底的双重保障

❌ 局限：

• 需要 Grok API（墙内用户可能需要镜像站）
• Tavily/Firecrawl API 依赖境外服务
• 主要面向 Claude Code，对其他 Client 的价值取决于它们对 MCP 工具的调用意愿

与同类工具的比较

GrokSearch 的差异化在于：双引擎 + 一键禁用官方工具，这是其他方案没有的组合。

总结

GrokSearch 解决的是 AI 编程助手领域一个很实际的问题：LLM 不愿意主动搜索。

它的双引擎设计（Grok 搜索 + Tavily/Firecrawl 抓取）保证了从搜索到内容获取的完整链路，而 toggle_builtin_tools 一键禁用官方工具的设计，则从机制上强迫 LLM 必须使用网络访问能力。

对于需要在真实网络环境中工作的 Claude Code 用户，GrokSearch 是一个值得配置的效率工具。

项目信息

• GitHub：GuDaStudio/GrokSearch ⭐ 1.6k
• 语言：Python 3.10+
• 框架：FastMCP 2.0+
• 许可证：MIT
• 安装：claude mcp add-json grok-search（见上文）