中文 | English

cyxj-groksearch

为 Claude Code 提供实时联网能力的 MCP 服务器：Grok AI 搜索、Tavily 高保真抓取/站点映射、Firecrawl 网页截图，内置多 key 轮询与自动 failover。

为什么用它，而不是 Claude Code 内置 WebSearch？

Claude Code 自带 WebSearch 和 WebFetch。这个 MCP 不是替代，而是补充——它提供内置工具做不到的能力：

• 多源交叉验证 — web_search 可通过 extra_sources 参数同步向 Tavily/Firecrawl 并行取独立信源，合并后一次返回，Claude 可在单次调用内对比多方索引结果。
• Grok 中转路由 — 可将 AI 搜索流量指向任意 OpenAI 兼容端点（官方 Grok API、自建镜像、中转站）。内置工具无法重定向。
• 原文全文抓取 — web_fetch 通过 Tavily Extract（Firecrawl 降级）获取 16 KB+ 结构化 Markdown 原文，而非摘要片段，适合钉死一手事实。
• 强制路由控制 — toggle_builtin_tools 把 WebSearch/WebFetch 写入项目 .claude/settings.json 黑名单，所有联网请求强制走本 MCP。可随时撤销。
• 多 key 轮询池 — Grok / Tavily / Firecrawl 三个 API 均支持逗号分隔多 key，遇到限速/报错自动 30 分钟 cooldown，无缝切下一个 key。

功能特性

• 8 个 MCP 工具，覆盖搜索、抓取、截图、站点映射、运行时控制
• Grok AI 搜索 + session 级信源缓存
• Tavily Extract 为主抓取，Firecrawl 自动降级
• Firecrawl JS 渲染截图（返回签名 GCS URL）
• 同一 Firecrawl key 池同时供 web_fetch 降级、extra_sources 补信源、web_screenshot 三用
• 内置连接诊断：配置检查 + 1-token 模型探针
• 通过 ~/.config/grok-search/config.json 持久化默认模型
• launcher 脚本自动聚合所有 TAVILY_API_KEY* 变量成多 key 轮询池

工具列表

安装与配置

前置条件

• uv — Python 包管理器
• Claude Code

方式 A — 从 GitHub 安装（推荐）

用 uvx 从 GitHub 直接安装并注册 MCP。只有 GROK_API_URL 和 GROK_API_KEY 必填，Tavily/Firecrawl 可选。

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": ["--from", "git+https://github.com/chenyuxiaojin/cyxj-groksearch@main", "grok-search"],
  "env": {
    "GROK_API_URL": "https://your-grok-endpoint/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "TAVILY_API_KEYS": "tvly-...",
    "FIRECRAWL_API_KEYS": "fc-..."
  }
}'

验证：claude mcp list 显示 grok-search ✓ 即成功。

方式 B — 本地源码 + launcher 脚本（开发调试）

克隆仓库后，在 Claude Code MCP 注册里把 command 指向 launcher 脚本。launcher 会加载 .env、自动聚合所有 TAVILY_API_KEY* 变量到轮询池，再用 uv run 从本地源码启动（改代码即时生效）。

{
  "grok-search": {
    "type": "stdio",
    "command": "/绝对路径/GrokSearch/grok-search-launcher.sh",
    "args": [],
    "env": { "GROK_SEARCH_ENV_FILE": "/绝对路径/你的/.env" }
  }
}

.env 默认取脚本同目录，可用 GROK_SEARCH_ENV_FILE 覆盖。参考 .env.example 查看所有变量。

环境变量

Firecrawl key 读取优先级：FIRECRAWL_API_KEYS → FIRECRAWL_API_KEY → FIRECRAWL_SCREENSHOT_API_KEYS → FIRECRAWL_SCREENSHOT_API_KEY

强制联网走本工具

安装后在对话里说「调用 toggle_builtin_tools，action=on」。这会把 WebSearch、WebFetch 写入当前项目 .claude/settings.json 的 deny 列表，所有联网请求强制路由到本 MCP。用 action=off 可恢复内置工具。

与同类工具对比

FAQ

不配 Tavily / Firecrawl 能用吗？
能。只有 GROK_API_URL 和 GROK_API_KEY 是必填项。不配 Tavily，web_fetch 和 web_map 会返回配置提示。不配 Firecrawl，web_screenshot 返回配置提示，web_fetch 的 Firecrawl 降级路径跳过。

与内置 WebSearch 的区别是什么？怎么强制走本工具？
内置 WebSearch 由 Claude 托管，无法重定向到自定义端点。本 MCP 路由到你自己的 Grok 端点，并增加多源聚合、全文抓取和 key failover。强制路由：调用 toggle_builtin_tools 设 action="on"；恢复内置：设 action="off"。

支持哪些 Grok 端点？
任意暴露了 /v1/chat/completions 和 /v1/models 的 OpenAI 兼容端点，包括官方 api.x.ai、自建镜像和商业中转站。GROK_API_URL 填含 /v1 的基础 URL。

多 key failover 怎么工作？
每个 API（Grok、Tavily、Firecrawl）都接受逗号分隔的多 key 列表，服务器按轮询顺序使用。某个 key 报错（限速或网络错误）后进入 30 分钟 cooldown，期间自动跳过。用 get_config_info 可查看当前 cooldown 状态。

连接有问题怎么排查？
调用 get_config_info。它会向 /models 发连接测试请求、发送 1-token 探针验证默认模型是否可用，并报告所有 key 池的 cooldown 状态。

环境要求

• Python 3.10+
• fastmcp >= 2.3.0、mcp[cli] >= 1.21.2、httpx[socks] >= 0.28.0、tenacity >= 8.0.0
• uv（用于安装和本地开发）

开发

cd GrokSearch
uv sync
uv run --extra dev pytest -v        # 跑测试
uv run --directory . grok-search    # 本地 stdio 调试

致谢

• 原版项目：GuDaStudio/GrokSearch（孙佬 @DaiSun）——LINUX DO 原帖
• 感谢 LINUX DO 社区，本项目源于站内佬友的分享

许可证

MIT License — 基于 GuDaStudio/GrokSearch 重写。