Claude Code接DeepSeek后，缺的那块Web搜索我补上了

最近我一直在折腾一件事：把 DeepSeek / Qwen / Kimi 这类第三方模型接进 Claude Code。

接进去以后，写代码、读文件、跑命令这些流程基本能用，但很快会碰到一个很现实的问题：

模型可以写代码，但它不一定能稳定联网查资料。

这在 coding agent 场景里挺致命。现在很多问题不是靠模型记忆就能答准的，比如：

某个库的最新 API 有没有改
某个 GitHub issue 有没有讨论过类似报错
某个 release note 里有没有 breaking change
Claude Code / MCP / 第三方 API 的接入方式有没有变
一个报错是不是最近版本才出现

如果没有可用的搜索和网页抓取工具，模型就很容易开始"凭印象回答"。于是我写了一个小工具：

CC Web MCP：给 Claude Code 第三方模型后端补联网能力的轻量 Web MCP。

GitHub：

github.com/JcDizzy/CC-...

PyPI：

pypi.org/project/cc-...

当前版本：0.1.5，MIT License，支持 Python 3.11 / 3.12 / 3.13。

先给安装方式

普通用户推荐直接用 uvx，不需要克隆仓库，也不需要提前创建虚拟环境：

powershell 复制代码

uvx cc-web-mcp init --runner uvx
uvx cc-web-mcp doctor

如果希望固定本文写作时的版本，或者刚升级后想强制刷新 uv 缓存，也可以写成：

powershell 复制代码

uvx --refresh-package cc-web-mcp cc-web-mcp@0.1.5 init --runner uvx --force
uvx --refresh-package cc-web-mcp cc-web-mcp@0.1.5 doctor

init --runner uvx 会做几件事：

创建用户配置文件
注册 Claude Code 用户级 stdio MCP
写入用户级 ~\.claude\CLAUDE.md 路由提示
合并 ~\.claude\settings.json hook 守卫，并在写入前备份

如果你之前用过旧版本、editable install、普通 pip 或旧的 uv 缓存路径初始化过，建议刷新一次：

powershell 复制代码

uvx --refresh-package cc-web-mcp cc-web-mcp@0.1.5 init --runner uvx --force

如果需要 PDF 文本提取能力，可以额外启用可选依赖：

powershell 复制代码

uvx --refresh-package cc-web-mcp cc-web-mcp[pdf]@0.1.5 init --runner uvx --with-pdf --force

诊断命令也走 uvx：

powershell 复制代码

uvx cc-web-mcp doctor --skip-network

这里特意强调一下：推荐安装方式是 uvx，所以普通用户机器上不一定有 cc-web-mcp.exe 在 PATH 里。文档里也保留了 py -3.11 -m cc_web_mcp ... 这种 pip / editable install 的兜底写法，但日常使用优先看上面这几条。

还有一个容易混淆的细节：用户平时运行的是 uvx cc-web-mcp ...，但初始化后 Claude Code 里最终保存的是两类命令：

MCP server：uvx cc-web-mcp@0.1.5
hook guard：uvx --from cc-web-mcp@0.1.5 cc-web-mcp hook-guard

前者负责启动 MCP server；后者只用于 Claude Code 的 hook 守卫。两者不要手动混成同一条命令。

这个工具解决什么问题？

它不是要替代官方 Claude 的 WebSearch / WebFetch。

如果你用的是官方 Claude Sonnet / Opus，正常情况下继续用 Claude Code 原生 Web 工具就好。cc-web 主要解决这个场景：

text 复制代码

Claude Code + 第三方 Anthropic-compatible API
比如 DeepSeek / Qwen / Kimi
        ↓
原生 WebSearch / WebFetch 不可用或不稳定
        ↓
模型查不了最新资料，只能靠旧知识猜
        ↓
用 cc-web 提供本地、只读、可控的网页搜索和抓取能力

一些第三方 Anthropic-compatible API 对原生 WebSearch 这类工具并不一定完整兼容。有时请求会在 API 侧直接失败，本地 hook 甚至还没来得及触发。

所以我的思路不是强行让第三方模型走 Claude Code 原生 Web 工具，而是给它一个专门的 MCP：搜索、抓取、摘要、诊断都在这个 MCP 里完成。

暴露了哪些工具？

目前有 4 个主要工具：

text 复制代码

research_brief
web_search
fetch_url
health_check

research_brief：优先用这个

这是我最推荐给 agent 调用的入口。

它会先搜索，再抓取少量来源的短正文，返回一个上下文友好的资料概览。适合这种流程：

text 复制代码

先查资料 → 快速理解背景 → 再决定是否读取某个具体页面

相比"搜一堆链接，再逐个全文抓取"，research_brief 更省上下文，也更符合 coding agent 的实际工作流。

web_search：只搜索，不抓全文

默认搜索链路是：

text 复制代码

DuckDuckGo HTML → Bing CN fallback

如果当前网络环境下 DuckDuckGo 不稳定，会继续尝试 Bing 中文入口。也可以配置 SearXNG。

这里需要提前说清楚：bing_cn 只是实用降级，不是全球搜索的等价替代。所以返回结果里会带 search_scope_note，提醒模型当前结果可能有区域偏置。

fetch_url：读取具体网页

用于抓取具体 URL，并转成 Markdown。

目前支持：

HTML 转 Markdown
纯文本 / Markdown 清洗
JSON 格式化
相对链接转绝对链接
分页读取
PDF 默认拒绝，可选通过 cc-web-mcp[pdf] 开启公开 PDF 文本提取

如果页面内容太长，它会返回下一段读取建议，避免模型反复读同一段。

health_check：让 agent 自查环境

这个工具检查依赖、配置和网络连通性。

命令行侧对应：

powershell 复制代码

uvx cc-web-mcp doctor

或者跳过真实网络访问：

powershell 复制代码

uvx cc-web-mcp doctor --skip-network

不只是"抓网页"，重点是让模型走对工具

实际用下来，真正麻烦的不是"怎么把网页转成 Markdown"，而是：

怎么让 Claude Code 里的第三方模型稳定走对工具。

所以 cc-web 做了两层路由。

1. CLAUDE.md 启动提示

init 会把路由提示写入用户级：

text 复制代码

~\.claude\CLAUDE.md

目标是让 DeepSeek / Qwen / Kimi 这类第三方模型一开始就知道：

text 复制代码

不要优先调用原生 WebSearch，应该用 cc-web。

这一步很重要，因为部分第三方 API 会在服务端直接拒绝 WebSearch，本地 PreToolUse hook 拦不到。

2. PreToolUse hook 守卫

init 也会更新用户级：

text 复制代码

~\.claude\settings.json

hook 主要负责：

默认只允许匹配配置的第三方模型调用 cc-web
官方 Claude 默认继续使用原生 WebSearch / WebFetch
第三方模型误用原生 WebFetch 时，拦截并提示改用 cc-web
如果确实想让官方 Claude 调用 cc-web fetch_url，可以显式打开配置

基础配置大概是：

json 复制代码

{
  "allowed_model_patterns": ["deepseek"],
  "search_providers": ["duckduckgo", "bing_cn"],
  "allow_fetch_url_for_claude": false,
  "block_native_web_for_allowed_models": true
}

想同时适配更多模型，可以改成：

json 复制代码

{
  "allowed_model_patterns": ["deepseek", "qwen", "kimi"]
}

安全边界做了什么？

这是给 agent 用的网页工具，所以我不想让它变成"模型想抓什么就抓什么"的裸奔版本。

目前默认做了这些限制：

只允许抓取 http/https
默认禁止抓取本机、内网、链路本地地址和云 metadata 地址
检查 DNS 解析后的 IP，避免公开域名解析到私网
检查 30x 重定向后的最终 URL
research_brief 在抓取搜索结果前会过滤非法 URL
Jina Reader fallback 也会重新做 URL 安全校验
即使开启 allow_private_networks，Jina fallback 也不会允许内网 URL 走第三方服务
缓存只在非内网模式下启用
不执行网页写入操作
不尝试绕过验证码、登录墙或 WAF

它不是安全神器，但至少不会把一个完全无边界的网页抓取器直接交给模型。

失败时给结构化诊断

真实抓网页时，失败很常见：

403 / 429
登录墙
验证码
WAF
JS 渲染页面
强反爬站点
网络超时

cc-web 不会尝试绕过这些限制，而是尽量返回结构化诊断。例如：

json 复制代码

{
  "error_type": "captcha_or_challenge",
  "retryable": false,
  "do_not_retry_reason": "Target returned captcha_or_challenge; repeating fetch_url with the same URL is unlikely to help.",
  "recommended_next_action": "Use search summaries, official sources, or another accessible source."
}

这样模型不太容易一直重复抓同一个失败页面，而是会换来源、用搜索摘要，或者先跑 health_check。

和现有工具相比有什么区别？

先说结论：cc-web 不是 Firecrawl / Tavily / Brave / Context7 的替代品。

这些工具各有强项。

Firecrawl / Tavily / Brave 更像专业搜索、抓取或网页研究服务，搜索质量和稳定性通常更好，但也更依赖外部 API 或商业服务。

Context7 更适合查某个库的最新文档。

普通 Fetch MCP 更轻，适合只读取网页。

cc-web 的取舍是：

默认不依赖商业 API
本地可控
用 uvx 一条命令初始化
更贴近 Claude Code + 第三方模型这个具体场景
对国内网络环境做一点 fallback
带工具路由、hook 守卫、doctor 诊断和 SSRF 防护

所以它的定位不是"最强网页工具"，而是：

Claude Code 第三方模型后端缺联网能力时，一个本地可控的补丁型工具链。

第一次怎么测？

安装完成后，可以在 Claude Code 里用第三方模型问一个小范围联网问题：

text 复制代码

使用 cc-web 查询 "Claude Code MCP PreToolUse hook permissionDecision"，先用 research_brief 获取资料概览，再总结当前推荐写法。

如果模型仍尝试调用原生 WebSearch，先检查 ~\.claude\CLAUDE.md。

如果模型尝试调用原生 WebFetch 并被 hook 拦截，说明 hook 已经生效，模型应该根据提示改用 cc-web fetch_url。

我个人建议优先让模型调用 research_brief。只有某个来源确实关键时，再用 fetch_url 单独读取完整页面。

适合谁？

比较适合：

用 DeepSeek API 接 Claude Code 的用户
用 Qwen / Kimi / 其他第三方 Anthropic-compatible API 接 Claude Code 的用户
希望模型能查官方文档、GitHub issue、release note、报错资料的人
需要轻量、本地、只读 Web MCP 的人
国内网络环境下想要 DuckDuckGo + fallback 的人

不太适合：

只用官方 Claude Code，不接第三方模型
需要高质量商业搜索 API
需要浏览器自动化、JS 渲染、登录态页面抓取
需要企业级稳定性、监控、配额和 SLA
主要需求是查库文档，这种场景 Context7 可能更合适

目前状态

这个项目已经从"本地脚本"整理成标准 Python package：

PyPI 包名：cc-web-mcp
推荐运行方式：uvx cc-web-mcp ...
console script：cc-web-mcp
初始化命令：init
诊断命令：doctor
PDF 提取：可选 extra，cc-web-mcp[pdf]
License：MIT
Python：3.11 / 3.12 / 3.13
当前版本：0.1.5

GitHub Release：

github.com/JcDizzy/CC-...

PyPI：

pypi.org/project/cc-...

后续计划

后续可能继续做：

GitHub issue / PR / release 专用工具
GitHub raw file / README 专用读取
更多搜索后端，例如 Tavily / Brave Search / Exa / Serper
更细的来源质量提示
更完整的联网 smoke test
更适合 DeepSeek / Qwen / Kimi 的工具调用提示

如果你也在用 DeepSeek / Qwen / Kimi 接 Claude Code，并且遇到原生 WebSearch / WebFetch 不可用或不稳定的问题，可以试试看。

也欢迎提 issue，尤其是这些方面：

Claude Code 工具名兼容问题
第三方模型是否会稳定调用 research_brief
DuckDuckGo / Bing CN 在不同网络下的可用性
官方文档或 GitHub 页面抓取质量
hook 误拦截 / 漏拦截
反爬诊断误判
安全边界问题