webcrawl-mcp 是一个轻量级 MCP（Model Context Protocol）服务器，旨在让 Claude Code 或任何兼容 MCP 的客户端具备抓取（scrape）、搜索（search）、映射（map）和爬取（crawl）网页的能力。它完全建立在免费开源的库之上，Firecrawl 仅作为可选回退方案，用于处理 JavaScript 渲染较重的站点（需要自备 API Key）。
设计思路
大多数网页抓取实际上并不需要无头浏览器。trafilatura 能在本地处理约 80% 的常见场景（文章、文档、博客），速度更快，并且把外部 API 的使用降到最低。该服务器把简单内容交给本地提取，只有在内容质量确实很差时才回退到 Firecrawl。
来源标识
抓取内容上的 source 字段取值可能为 static_http、static_http_retry、firecrawl_transport_fallback 或 firecrawl_quality_fallback，用于说明内容由哪条路径产生。
环境要求
需要 Python 3.12 及以上版本。
快速冒烟测试
运行后应打印 “Webcrawl MCP server running”，然后用 Ctrl-C 正常退出。
从源码安装（开发用）
通过源码检出方式进行安装和开发。
配置 MCP 客户端
在项目根目录创建 .mcp.json（或合并进 ~/.claude/settings.json）。该方式使用 uvx 在临时环境中运行包，无需手动安装。如果 uvx 不可用，可用 pip install webcrawl-mcp 安装，并把 "command" 设为 "webcrawl-mcp" 且不带参数。
若使用源码检出（开发），把 command 指向虚拟环境中的 Python，并使用 "args": ["-m", "webcrawl_mcp"]。
然后在 Claude Code 会话中运行 /mcp，应该能看到 webcrawl 被列出，并带有四个工具。
Claude Desktop 使用同样的 JSON 结构，放入 claude_desktop_config.json（各操作系统路径参见 Anthropic 文档），编辑后重启 Claude Desktop。
其他 MCP 客户端（Cursor、Cline、Continue、Zed 等）使用标准化的 command / args / env 结构，具体放置位置请查阅对应客户端的 MCP 文档。
验证是否工作
可以要求你的 agent 执行类似操作： 使用 webcrawl_scrape 工具抓取 https://docs.python.org/3/library/asyncio.html 并总结第一节内容。 你应在客户端 UI 中看到工具调用，随后看到基于实时页面内容的摘要。若无反应，参见排障部分。
环境变量
请在 MCP 配置的 env 块中设置，而不要在 shell 中设置——MCP 服务器运行在客户端之下，而不是你的终端中。
回退行为
抓取器会区分提取质量失败与传输失败，并通过 source 字段报告内容由哪条路径产生。
提取质量路径（默认）： trafilatura 从 HTML 中提取正文 → source: static_http。 若失败或返回少于 200 字符，markdownify 转换原始 HTML。 若结果仍然质量不佳且已设置 FIRECRAWL_API_KEY，则作为最后手段使用 Firecrawl → source: firecrawl_quality_fallback。
传输路径（需主动开启）： 若请求返回 403、429 或 503（典型的反爬响应）： 在 POLITE_MODE=true（默认）下，带 Retry-After 头的 429 会获得一次有界重试原始请求 → 成功时 source: static_http_retry。 在 FALLBACK_ON_TRANSPORT_ERROR=true 且已设置 FIRECRAWL_API_KEY 时，请求会改走 Firecrawl 而不是抛错 → source: firecrawl_transport_fallback。 否则，传输错误会抛给调用方（当前行为）。
没有 Firecrawl Key 时，该工具完全自包含且免费；没有 Key 时 FALLBACK_ON_TRANSPORT_ERROR 不产生效果。
排障
客户端在 MCP 服务器中未列出 webcrawl：几乎总是命令路径问题，必须是虚拟环境中 Python 二进制的绝对路径，而不是简单的 python。可在终端测试：你配置的路径 -m webcrawl_mcp 应打印 Webcrawl MCP server running。 ModuleNotFoundError: webcrawl_mcp：可能是 pip install -e . 与 command 不在同一个虚拟环境中执行，或 PYTHONPATH 缺失/错误。请确认两者指向同一份检出。 Python 版本不匹配：需要 3.12+，虚拟环境内 python --version 应报告 ≥ 3.12，否则用更新版本 Python 重建虚拟环境。 抓取返回文本很少：部分站点使用 JavaScript 渲染，无法静态提取。可设置 FIRECRAWL_API_KEY 启用回退路径，或接受该工具不适用于该特定站点。 搜索慢或被限流：DuckDuckGo 对突发查询会限流。请拉长搜索间隔，或减少 num_results。
负责任使用
该工具用于为研究、编码辅助及类似合法用途获取公开网页内容。你需要负责：遵守目标站点的服务条款和 robots.txt；不要给服务器造成过载（内置的按域名限流有帮助，但不要绕过它）；遵守你所在司法辖区关于自动访问和数据使用的适用法律。
许可证
MIT —— 见 LICENSE。
致谢
构建于 trafilatura、httpx、beautifulsoup4、markdownify、ddgs 和 fastmcp 之上。Firecrawl 集成使用公开的 Firecrawl API（无关联关系）。
