WebSearch-MCP

English | 简体中文

面向 Cherry Studio、Claude Code 与 Codex 的标准 MCP 网络搜索服务

深度检索 · 270 秒主动预算 · Grok 并发 2 · Tavily 每 Key 并发 1

WebSearch MCP 是什么

WebSearch MCP 把 Grok 的 AI 联网搜索与 Tavily 的结构化检索、网页提取和站点映射组合成一个标准 MCP stdio 服务。它不依赖某个客户端的私有能力，也不会修改 Cherry Studio、Claude Code 或 Codex 的本地配置。

MCP Client ──stdio──► WebSearch MCP
                       ├─ web_search ─► Grok /v1/chat/completions + 可选 Tavily 信源
                       ├─ get_sources ─► 搜索信源缓存
                       ├─ web_fetch  ─► Tavily Extract
                       └─ web_map    ─► Tavily Map

Related MCP server: Tavily Web Search MCP Server

为什么选择 WebSearch MCP

适合以下场景：

• 让编码助手检索最新官方文档、Release、Issue 和技术资料。

• 获取带可追溯信源的实时搜索答案。

• 把网页正文提取为 Markdown，或发现文档站点的 URL 结构。

• 在多个 MCP 客户端之间复用相同工具 Schema 和环境变量。

当前状态

• P0 仓库与测试基线：已完成。

• P1 旧抓取服务清理与模块化：已完成。

• P2 Tavily 多 Key 可靠性：已完成。

• P3 Grok 单强模型与重试：已完成。

• P4 统一返回协议：已完成。

• P5 搜索 Prompt 与搜索质量重构：已完成。

• 搜索超时与并发治理：已完成自动化实现；等待 Cherry Studio 300 秒外层超时人工复验。

• 外部项目代码审计和有界运行时缓存：已完成；运行时固定使用 Chat Completions。

• 下一阶段：P6 跨客户端真实人工验收。

完整需求与验收标准见 开发路线文档。

快速开始

1. 准备环境

需要：

• Python 3.10+

• uv

• 一个 OpenAI 兼容的 Grok API 地址和 Key

• 可选的 Tavily Key；web_fetch、web_map 和额外 Tavily 信源需要它

2. 添加 MCP 服务

以下配置可直接复制；将 API 地址、Key 和模型替换为你的实际值。GROK_API_URL 必须是以 /v1 结尾的 API 根地址，本项目只调用 /v1/chat/completions 和 /v1/models。

Cherry Studio（JSON）

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Timmyzzo/WebSearch-MCP",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.example/v1",
        "GROK_API_KEY": "your-grok-api-key",
        "GROK_PRIMARY_MODEL": "grok-4-fast",
        "GROK_MODEL_MAX_ATTEMPTS": "12",
        "GROK_MAX_CONCURRENCY": "2",
        "WEB_SEARCH_TOTAL_TIMEOUT": "270",
        "GROK_SINGLE_ATTEMPT_TIMEOUT": "120",
        "GROK_RETRY_MULTIPLIER": "1",
        "GROK_RETRY_MAX_WAIT": "10",
        "GROK_RETRYABLE_UPSTREAM_CODES": "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error",
        "TAVILY_PER_KEY_MAX_CONCURRENCY": "1",
        "TAVILY_API_KEYS": "tvly-key-1,tvly-key-2"
      }
    }
  }
}

Cherry Studio 还需把 MCP 工具调用超时设置为 300 秒。

Claude Code / cc（完整 JSON）

把下面对象保存为 JSON，或将其作为 claude mcp add-json 的参数：

{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/Timmyzzo/WebSearch-MCP",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.example/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "GROK_PRIMARY_MODEL": "grok-4-fast",
    "GROK_MODEL_MAX_ATTEMPTS": "12",
    "GROK_MAX_CONCURRENCY": "2",
    "WEB_SEARCH_TOTAL_TIMEOUT": "270",
    "GROK_SINGLE_ATTEMPT_TIMEOUT": "120",
    "GROK_RETRY_MULTIPLIER": "1",
    "GROK_RETRY_MAX_WAIT": "10",
    "GROK_RETRYABLE_UPSTREAM_CODES": "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error",
    "TAVILY_PER_KEY_MAX_CONCURRENCY": "1",
    "TAVILY_API_KEYS": "tvly-key-1,tvly-key-2"
  }
}

Linux/macOS 安装命令：

claude mcp add-json grok-search --scope user "$(cat grok-search.json)"

PowerShell 安装命令：

claude mcp add-json grok-search --scope user (Get-Content .\grok-search.json -Raw)

Codex / cx（官方 config.toml 格式）

Codex 的持久化 MCP 配置格式是 TOML，不是 JSON。将以下完整配置加入 ~/.codex/config.toml：

[mcp_servers.grok-search]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/Timmyzzo/WebSearch-MCP",
  "grok-search",
]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.grok-search.env]
GROK_API_URL = "https://your-api-endpoint.example/v1"
GROK_API_KEY = "your-grok-api-key"
GROK_PRIMARY_MODEL = "grok-4-fast"
GROK_MODEL_MAX_ATTEMPTS = "12"
GROK_MAX_CONCURRENCY = "2"
WEB_SEARCH_TOTAL_TIMEOUT = "270"
GROK_SINGLE_ATTEMPT_TIMEOUT = "120"
GROK_RETRY_MULTIPLIER = "1"
GROK_RETRY_MAX_WAIT = "10"
GROK_RETRYABLE_UPSTREAM_CODES = "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error"
TAVILY_PER_KEY_MAX_CONCURRENCY = "1"
TAVILY_API_KEYS = "tvly-key-1,tvly-key-2"

更详细的验证步骤见：

• 客户端配置指南（中文）

• Client setup guide (English)

3. 验证

在客户端中确认能发现以下核心工具：

web_search
get_sources
web_fetch
web_map
get_config_info
switch_model

建议先调用 get_config_info 检查脱敏配置和 Grok /models 连接，再执行一次 web_search。

配置

只配置 Grok 时，web_search 仍可使用。设置 TAVILY_ENABLED=false 会禁用 Tavily，即使环境中存在 Tavily Key。

模型解析优先级为：当前进程中 switch_model 设置的模型、非空 GROK_PRIMARY_MODEL、非空 GROK_MODEL、配置文件中的模型、默认值 grok-4-fast。环境变量仅包含空白时视为未设置。服务不会自动降级到较弱备用模型；请直接配置你希望使用的最强可用模型。

默认可重试上游错误码为 rate_limit、rate_limit_exceeded、too_many_requests、upstream_error、server_error、service_unavailable、temporarily_unavailable、overloaded、overloaded_error 和 internal_error。这解决了部分中转站用 HTTP 200 包装临时错误、导致标准 HTTP 状态判断失效的问题。设置 GROK_RETRYABLE_UPSTREAM_CODES 会替换默认列表；若要增加自定义错误码，请在配置中同时保留所需默认项。

对于单次请求成功率约 40% 的端点，默认 12 次尝试在各次结果近似独立时，理论成功概率约为 99.78%，平均真实请求数约为 2.5。实际调用仍受 WEB_SEARCH_TOTAL_TIMEOUT 限制；如果错误经常表现为长时间超时，而不是数秒内返回错误码，需要同步增大服务端总预算和客户端工具超时。

工具概览

所有工具还统一返回 status、error、error_detail 和 partial。web_search 的 query 是唯一必填参数。规划工具是可选能力，不是搜索前置步骤；所有 thought 参数均为可选。

搜索质量与深度优先策略

每次 web_search 都使用有界 deep 策略：先检索至少 5 个真正不同的视角，再选择至少 2 个最相关或最不确定的方向继续深挖，因此普通问题通常形成 7–12 次检索动作。人物身份、强时效、高风险、比较、小众和争议问题通常提升到 10–16 次。简单事实和单一官方文档也不会低于这一下限，但答案篇幅仍按问题本身保持简洁。

这一执行下限与原项目已验证策略对齐：原项目要求 5 个以上广度视角和至少 2 个深挖方向；本项目在此基础上增加确定性预算、原生语言与实体相关语言检索、来源等级、反证检查和 Tavily 候选证据综合。微小措辞变化不能被计为不同视角，达到次数也不能替代证据质量。

这些数量是 Prompt 中的有界搜索预算，不会形成无限工具循环。模糊实体调查会扩展别名、账号、组织、团队、协作者、事件与时间范围，并把结论分为直接确认、强支持、合理候选和冲突/排除，同时给出可解释的置信度。缺少单一实名绑定页不会让搜索提前停止，但不会把推测伪装成事实。用户查询与平台提示以 JSON 数据传递；网页、搜索片段和用户输入中的指令不能覆盖系统搜索规则。

当 extra_sources>0 时，Tavily 会先提供结构化 URL、标题和摘要候选，Grok 再结合自身联网搜索完成证据核对与答案综合；候选内容仍被视为不可信资料，不会覆盖系统规则。Tavily 失败时 Grok 仍可返回 partial_success，Grok 失败时 Tavily 仍不能替代最终答案。

Grok 上游协议固定为流式 Chat Completions。服务不会读取协议选择环境变量，不会调用 /responses，也不会在失败时自动切换端点；中转站只需兼容 /v1/chat/completions 和 /v1/models。

通用来源优先级为：官方文档/标准/法规/原始数据/论文与系统综述，权威机构和项目维护团队，有事实核查的专业媒体，专业实践经验，最后才是博客、论坛和社交媒体线索。关键结论优先使用高等级来源；转载同一原始消息不算独立证据，证据不足时会明确说明。

领域策略包括：

• 软件与 GitHub：优先当前默认分支文档、README、Release、Changelog、迁移指南、API Reference、commit、issue、PR 和维护者说明，并核对稳定版、发布日期、弃用与最终合并代码。

• 健身、健康、营养与恢复：区分研究支持、专家实践和运动员个人经验，结合训练年龄、伤病、基础、恢复、设备和周期；伤病、疾病、药物或极端饮食明确医疗评估边界。

• 汽车和其他高风险安全问题：优先官方测试与真实事故数据，区分碰撞避免和乘员保护，不跨不兼容标准机械比较星级，并说明统计限制和不确定性。

• 小众、模糊或证据稀缺问题：先定义概念，必要时使用同义词或多语言检索，主动寻找反例、失败案例和不同学派，并尝试用两类独立来源交叉验证。

“最新、当前、今天、现版本、仍然支持”等查询会使用运行时实际日期和时区，核对版本、发布日期和资料更新时间。复杂答案按需要说明证据等级、争议、限制、适用范围和不确定性；简单答案不会被强制套用冗长模板。P4 的 success、partial_success、error、error_detail 和全部兼容字段保持不变。

超时与并发治理

Cherry Studio 建议把 MCP 工具外层超时设置为 300 秒；这是避免客户端过早产生 -32001 的安全上限，不是性能目标。服务端单次 web_search 默认使用 WEB_SEARCH_TOTAL_TIMEOUT=270 的总墙钟预算，并在该预算内主动返回成功、部分成功或结构化错误，为 MCP 序列化、进程调度和客户端传输预留约 30 秒。

Grok 单次读取上限由 GROK_SINGLE_ATTEMPT_TIMEOUT 控制，默认 120 秒；每次真实尝试的实际可用时间会缩短为“单次上限与当前剩余总预算中的较小值”。GROK_MODEL_MAX_ATTEMPTS=12 只表示最多 12 次真实 HTTP 请求，不保证一定执行 12 次：等待 Grok 槽位、Tavily Key 槽位、HTTP 传输、流读取、指数退避和 Retry-After 都消耗同一个总预算；剩余预算不足以容纳合理的新尝试时会提前停止。

同一 MCP 进程默认最多同时执行 2 个 Grok HTTP 请求。Tavily Search、Extract、Map 共用 Key 健康与占用状态，每个 Key 同时最多 1 个真实请求；多个健康 Key 可以各承担一个并发请求。所有槽位在成功、错误、取消、超时和流中断路径中释放，重试也必须重新排队。预算终止诊断会区分 max_attempts_exhausted、non_retryable_error、total_budget_exhausted 和 concurrency_queue_timeout，并报告配置/实际尝试数、耗时、预算与排队时间。

统一返回协议

status 只有三种稳定值：

• success：工具目标完整完成。合法的空信源列表可以成功，例如 Grok 给出有效答案但没有来源。

• partial_success：已返回可用结果，但某个补充组件或非关键步骤失败。例如 Grok 成功、Tavily 补充失败；规划尚未完成；站点映射包含部分无效项。

• error：当前工具目标未完成。空答案、空抓取内容、空 URL 映射、配置错误和上游失败都不会伪装成成功。

规范错误位于 error_detail：

{
  "code": "tavily_service_unavailable",
  "message": "Tavily 服务暂时不可用",
  "service": "tavily",
  "retryable": true,
  "http_status": 503,
  "upstream_code": "upstream_unavailable",
  "diagnostics": {
    "service_circuit": {"state": "open", "retry_after_seconds": 30}
  }
}

诊断信息只包含必要的脱敏字段，不包含 Grok/Tavily Key、Authorization 头、可能回显凭据的响应正文、Python traceback 或内部对象表示。结构化错误只结束当前工具调用，stdio MCP 进程仍可发现工具并执行后续调用。

兼容字段映射：

典型返回如下。

web_search 完整成功；有效答案没有来源仍是成功：

{"status":"success","session_id":"abc123","content":"有效答案","sources_count":0,"error":null,"error_detail":null,"partial":false}

Grok 成功但 Tavily 补充失败：

{"status":"partial_success","session_id":"abc123","content":"有效答案","sources_count":0,"partial":true,"error":null,"error_detail":{"code":"tavily_all_keys_unavailable","message":"所有 Tavily Key 均不可用","service":"tavily","retryable":false,"http_status":401,"upstream_code":"invalid_api_key","diagnostics":{"key_statuses":[{"fingerprint":"tvly…1234","state":"invalid"}]}},"tavily_error":{"code":"tavily_all_keys_unavailable","message":"所有 Tavily Key 均不可用"}}

Grok 最终失败时，即使 Tavily 成功也不会伪装为答案：

{"status":"error","session_id":"abc123","content":"","sources_count":0,"error":"grok_primary_failed","error_detail":{"code":"grok_primary_failed","message":"Grok 模型调用失败，已用尽最大尝试次数","service":"grok","retryable":true,"http_status":503,"upstream_code":"upstream_unavailable","diagnostics":{"primary_attempts":5,"fallback_attempts":0,"total_attempts":5,"termination_reason":"max_attempts_exhausted","configured_max_attempts":5,"actual_attempts":5,"elapsed_ms":120000,"budget_ms":270000,"queue_wait_ms":0}},"partial":false}

其他工具示例：

{"tool":"get_sources","status":"success","session_id":"abc123","sources":[],"sources_count":0}
{"tool":"web_fetch","status":"success","url":"https://example.com","content":"# Page","provider":"tavily"}
{"tool":"web_map","status":"error","base_url":"https://example.com","results":[],"error_detail":{"code":"tavily_no_urls","message":"Tavily 请求成功，但没有发现可返回的 URL","service":"tavily","retryable":false,"http_status":null,"upstream_code":null,"diagnostics":{"upstream_succeeded":true,"empty_result":true}}}
{"tool":"get_config_info","status":"partial_success","partial":true,"configuration":{"GROK_API_KEY":"未配置"},"connection_test":{"status":"配置错误"},"error_detail":{"code":"grok_configuration_error","message":"GROK_API_KEY 未配置","service":"grok","retryable":false,"http_status":null,"upstream_code":null,"diagnostics":{"configuration":"grok"}}}
{"tool":"switch_model","status":"success","success":true,"previous_model":"grok-4-fast","current_model":"grok-3-mini","message":"主模型已切换"}
{"tool":"plan_intent","status":"partial_success","partial":true,"session_id":"plan123","plan_complete":false,"phases_remaining":["complexity_assessment","query_decomposition"],"error_detail":{"code":"planning_incomplete","message":"搜索计划尚未完成，可继续提交剩余规划阶段","service":"planning","retryable":true,"http_status":null,"upstream_code":null,"diagnostics":{"phases_remaining":["complexity_assessment","query_decomposition"]}}}

Grok Chat 协议、单强模型与最多五次真实尝试

服务只使用流式 Chat Completions。OpenRouter 地址会继续为模型追加兼容的 :online 后缀；任何失败都只在同一个 /v1/chat/completions 端点和当前模型上按规则重试。

每次调用只使用用户配置的当前模型。408、429、5xx、连接失败、连接/读取超时、完整内容产生前或流式传输中的中断，可识别的中转站“上游账号不可用/死号/账号池不可用”，以及 GROK_RETRYABLE_UPSTREAM_CODES 列出的 HTTP 200 内嵌错误，会按带随机抖动的指数退避重试，默认最多执行 12 次真实请求。

重试不会突破 WEB_SEARCH_TOTAL_TIMEOUT，也不会绕过 GROK_MAX_CONCURRENCY。认证、参数、模型不存在和无权限错误会以“因不可重试错误提前停止”结束；只有确实达到配置上限才报告“已用尽最大尝试次数”。总预算或并发排队耗尽使用独立终止原因和结构化诊断。

模型不存在或无权限会立即停止；模型暂时不可用会继续重试当前模型。明确的 400/422 参数错误和 401/403/API Key 认证失败也会立即停止。错误分类同时检查 HTTP 状态、OpenAI 兼容错误对象、错误码、错误类型和正文语义。

流内容会在服务端完整缓冲并校验结束标志。流在产生部分内容后中断时，残缺内容不会作为成功答案返回、缓存或提取来源。最终失败返回 grok_error，包含当前模型、真实尝试次数、最后错误分类、状态码/上游错误码，并保留值为 null/0/false 的旧备用模型兼容字段；不会包含 API Key 或 Authorization 值。

switch_model(model) 保持旧调用形式不变：它更新当前进程使用的模型，并将 primary_model（同时保留兼容的 model 字段）写入本地配置。

多 Tavily Key

可以使用逗号、分号或换行配置多个 Key：

TAVILY_API_KEYS=tvly-key-1,tvly-key-2,tvly-key-3

正常请求会在健康 Key 间公平轮询，Search、Extract、Map 共享同一套运行时状态：

• healthy：正常参与轮询。

• cooldown：临时限流、超时、网络错误或临时服务异常，冷却后重新探测。

• quota_exhausted：额度耗尽，使用较长冷却时间。

• invalid：Key 无效或被撤销，本进程内不再使用。

Key 的“忙碌”是独立于上述健康状态的瞬时占用信息，不会被误判为冷却、额度耗尽或失效。同一 Key 忙碌时会优先选择其他健康空闲 Key；如果所有健康 Key 都忙碌，则在当前工具预算内等待最早可用槽位。

401/403 会使当前 Key 失效；429 会根据错误码、正文和 Retry-After 区分临时限流与额度耗尽；400/422 直接返回参数错误；404 提示检查 TAVILY_API_URL。多个不同 Key 出现相同 5xx 或网络错误时会触发服务级熔断，冷却后仅允许一次半开探测。

所有 Key 不可用时，web_fetch 和 web_map 返回 status="error"、tavily_all_keys_unavailable 及脱敏状态摘要。web_search 会保留已有 Grok 结果，返回 status="partial_success"，同时设置 partial=true 并保留 tavily_error。该错误只终止当前工具调用，不会退出 MCP 进程。

有界运行时缓存

搜索信源会话只保存在当前 MCP 进程内，最多 256 项并在 1 小时后过期；get_sources 对过期会话返回 session_id_not_found_or_expired。模型目录的成功结果缓存 5 分钟，之后重新读取 /models；失败不会被缓存为空结果。服务不长期缓存最终答案，也不会默认把完整搜索正文写入磁盘。

常见问题

客户端找不到工具

确认 uvx 在客户端进程的 PATH 中，并检查仓库地址、命令名 grok-search 和 JSON/TOML 语法。Windows 客户端如果找不到 uvx，可填写其绝对路径。

Grok 搜索可用，但抓取或映射失败

web_fetch 和 web_map 依赖 Tavily。调用 get_config_info，确认 Tavily 已启用并配置了 TAVILY_API_KEY 或 TAVILY_API_KEYS。

企业网络出现证书错误

在 uvx 参数开头加入 --native-tls，让 uv 使用系统证书库。完整示例见客户端配置指南。

是否会泄露 API Key

配置诊断只返回脱敏 Key。不要把真实 Key 写入仓库、Issue、日志截图或客户端共享配置。

Cherry Studio 仍显示 -32001: Request timed out

把 Cherry Studio 的 MCP 工具超时设置为 300 秒，并确认服务端没有把 WEB_SEARCH_TOTAL_TIMEOUT 配置为 300 秒或更高。默认 270 秒会先返回业务层结构化超时；300 秒只是客户端安全上限。

本地开发

git clone https://github.com/Timmyzzo/WebSearch-MCP
cd WebSearch-MCP
uv sync --extra dev
uv run ruff check .
uv run pytest
uv run python -m build

更多模块说明、测试范围和阶段边界见 开发者指南。

外部项目的代码级对比、许可证边界和采用/拒绝理由见 外部项目实现分析。

许可证

MIT License