Grok SearXNG Adapter

自用 fork，AI 生成，不负责。 本仓库把 Grok/xAI Responses API 的 web_search 重写为单容器，同时提供 SearXNG 兼容 HTTP 接口与 Streamable HTTP MCP。代码由 AI 辅助生成，仅供本人部署使用，不提供任何稳定性承诺或售后支持。能用就拿走，不能用请不要提 issue 索赔。

把 Grok/xAI Responses API 的 web_search 包装成 SearXNG 兼容的 HTTP 搜索接口，供 LobeHub 与 Open WebUI 使用；同时提供 Streamable HTTP MCP 端点，给支持 MCP 的 Agent 复用同一份 Grok 搜索与 Firecrawl 原文抓取能力。服务只使用本地 Docker Compose 构建，不推送镜像。

web_search 是 xAI 的服务端工具：它可在一次请求内搜索，并按模型需要浏览网页。/search 适配器要求模型在最终文本中返回带 URL 的 JSON 结果，这是兼容中转最稳定的契约；若中转未按要求输出 JSON，才无额外请求地尝试读取其原生来源字段。

同一容器的两条入口

同一个 FastAPI/ASGI 进程在 Docker 容器内同时提供：

• GET/POST /search：SearXNG 兼容 JSON，服务 LobeHub 与 Open WebUI。

• /mcp：Streamable HTTP MCP（stateless），提供 Grok 搜索与 Firecrawl 原文抓取。

MCP 默认工作流是“先搜索，再按需读取原文”：

Agent
  ├─ web_search(query) ──> Grok web_search ──> URL、标题、摘要
  └─ web_fetch(urls)  ───> Firecrawl       ──> 原始 Markdown + metadata

Grok 内部浏览过的完整页面内容不会通过 Responses API 无损暴露。Firecrawl web_fetch 的作用是把 Agent 选中的原始网页正文真正放回 Agent 上下文，而不是 给 Grok 的回答再做一次摘要。普通搜索不会自动调用 Firecrawl，避免增加延迟和费用。

/mcp 默认暴露 web_search 与 web_fetch 两个只读工具；可选的 web_research （让 Grok 直接返回带引用的综合回答）由 MCP_RESEARCH_ENABLED 控制是否暴露，默认关闭。

Related MCP server: mcp-firecrawl

部署

cp .env.example .env
# 编辑 .env，填入 GROK_BASE_URL、GROK_API_KEY、API_KEY
cp docker-compose.example.yml docker-compose.yml
# 按需编辑 docker-compose.yml（端口、BIND_ADDRESS 等）
docker compose up -d --build

仓库只提交 docker-compose.example.yml；你的 docker-compose.yml 由 cp 生成，被 .gitignore 忽略，可以放本机定制。Compose 只在服务器本机构建镜像，不会推送到任何镜像仓库。默认监听 127.0.0.1:8080；需要让其他机器访问时，设置 BIND_ADDRESS=0.0.0.0 并由防火墙或反向代理保护。

环境变量

MCP 与 Firecrawl：

接口

GET /search?q=OpenAI&format=json&count=5 和 POST /search 都返回 SearXNG JSON。请求必须带以下任一头：

Authorization: Bearer <API_KEY>
X-API-Key: <API_KEY>

若客户端只有 URL 配置、无法添加请求头（常见于 SearXNG 集成），在 URL 保留查询参数：

http://<server>:18763/search?api_key=<API_KEY>

查询参数会出现在客户端配置和部分访问日志中；优先使用请求头，或只在受信任的私有部署中使用该方式。LobeHub 本身不提供独立 API Key 字段，因此它只能使用此方式。

健康检查无需鉴权：GET /healthz。

MCP 端点 /mcp

/mcp 是 Streamable HTTP MCP（stateless，每次请求独立会话，无需 Mcp-Session-Id）。鉴权与 /search 共用 API_KEY，只接受请求头，不读 URL 查询参数：

Authorization: Bearer <API_KEY>
X-API-Key: <API_KEY>

工具：

• web_search(query, max_results?, search_mode?)：复用与 /search 相同的 Grok provider；返回 {query, results:[{url,title,content,source_type}]}。search_mode 取 balanced/realtime/social/unrestricted，作为提示影响结果偏好，不屏蔽任何站点。

• web_fetch(urls, question?, max_chars?)：用 Firecrawl 抓取已知 URL 的原始 Markdown；按 URL 独立记录错误，允许部分成功；超长正文按 FETCH_MAX_CHARS 裁剪并标记 truncated=true。只允许 HTTP/HTTPS，拒绝解析到私网/回环的地址与重定向，降低 SSRF 风险。

• web_research(query)：可选（MCP_RESEARCH_ENABLED=true 时才暴露）。让 Grok 综合搜索、浏览并带引用回答；返回 {query, answer, sources, limitations}。这是二手综合结果，需要原文时仍应 web_fetch。

客户端配置

• LobeHub：设置 SEARXNG_URL=http://<server>:8080?api_key=<API_KEY>。LobeHub 会自动追加 /search；适配器会兼容其把 /search 拼入 api_key 值的请求形式。

• Open WebUI：选择 SearXNG，URL 填 http://<server>:8080/search?api_key=<API_KEY>。如界面提供独立 API Key 字段，也可改用 X-API-Key。

LobeHub 的内置 Web Search 与模型内置搜索是不同路径。若要使用模型的服务端搜索，请在 Agent 中关闭 lobe-web-browsing/search 与 crawlMultiPages，避免“LobeHub 搜索 + Jina 抓取”和模型内置浏览重复执行。

延迟与稳定性

• 每次请求只进行一次 Grok web_search 调用，并以模型最终输出的结构化 JSON 作为主结果来源。

• 原生 sources/citations 仅在模型没有按约定输出 JSON 时使用；它是无额外请求的兼容兜底，不是主路径。

• SearXNG 格式只能表达 URL、标题和短摘要，不能把 Grok 服务端浏览到的完整页面上下文无损传给 LobeHub。深度研究应使用 /mcp 的 web_search + web_fetch，或单独的 Grok/MCP 工具。

• /mcp 使用 stateless Streamable HTTP：每个请求独立处理，客户端不需要维护 Mcp-Session-Id。搜索与 fetch 不自动串联，避免每次查询都承担抓取延迟。

更新

git pull
docker compose up -d --build