web_url_read是 mcp-searxng 中让 AI 助手读取网页和 PDF 的核心工具：抓取任意 URL 并返回可读 Markdown，还能用section按标题精准截取章节、用readHeadings先看页面结构。本文讲清它的全部参数与实战用法。

快速上手：先搜索，再读页

mcp-searxng 是运行在 SearXNG 之上的私有 Web 搜索 MCP 服务器，连接 Claude、Cursor 等任意 MCP 客户端。典型工作流只有两步：

1. 调用searxng_web_search搜索，从结果里挑出目标链接
2. 调用web_url_read并传入该 URL，拿到整页可读内容

⚡ 注意：web_url_read直接抓取目标网站，不经过 SearXNG，因此搜索和读取可以完全独立测试。

web_url_read 的 6 个参数速查表

工具定义见 src/types.ts，完整参数说明见官方工具文档 docs/tools.md：

多参数同时给出时的处理顺序（见 applyPaginationOptions）：

readHeadings→section→paragraphRange→startChar/maxLength

也就是说：先用标题定位章节，再做段落过滤，最后按字符数截断——这正好构成"由粗到细"的读取策略。

如何查看页面结构：readHeadings 参数

面对长文档，直接全量读取既慢又浪费上下文。推荐的第一招是"先看目录，再取内容"：

{"url":"https://example.com/guide","readHeadings":true}

返回该页所有 Markdown 标题（每行一个），页面没有标题时返回提示No headings found in the content.。

📌 两个重要规则：

• readHeadings是独立模式：一旦设为true，其他提取参数（section、maxLength等）一律不生效
• 标题列表用于挑选下一轮section要用的关键词

按标题定位章节：section 参数

section是"按标题定位内容"的关键，提取逻辑见 extractSection：

• 匹配规则：在所有标题行中查找包含section文本的那一行（#到######均可），匹配不区分大小写，传部分文字也能命中
• 截取范围：从命中标题开始，一直到下一个同级或更高级的标题为止；子标题（更深层级）的内容会一并包含

例如某文档的结构是：

# Getting Started ## Installation ## First Search # Troubleshooting

传"section":"installation"会返回## Installation到## First Search之间的全部内容，而不是整页。

📐 一个实用组合：先用readHeadings:true确认标题原文，第二次调用再用section取章节。两步调用成本远低于"全文拉回来再筛选"，对 AI 助手的上下文消耗尤其友好。

若标题没找到，工具会明确返回：

Section "xxx" not found in the content.

此时回到标题列表核对原文即可，不必盲目重试。

读取 PDF：文本提取规则与限制

web_url_read对application/pdf走专门的解析路径（src/pdf-reader.ts），在独立、资源受限的 worker 中提取文本：

📄 需要特别注意：不支持 OCR。纯扫描版/图片型 PDF 会返回说明文字而非正文：

No extractable text (likely a scanned/image PDF; OCR is not supported).

其他常见 PDF 提示及含义：

提取成功的 PDF 文本会以text代码块形式返回，与网页 Markdown 一样可以继续套用section等过滤参数。

分页与段落过滤：控制返回量

字符级分页——大页面可以分段读取，例如先取前 4000 字符：

{"url":"https://example.com/article","maxLength":4000}

接着用startChar读后续部分，实现翻页式阅读。注意maxLength只限制返回文本长度，不会降低下载大小限制。

段落级过滤——paragraphRange按空行分隔的段落计数，支持三种写法：

• '3'：只要第 3 段
• '1-5'：第 1 到 5 段
• '10-'：第 10 段直到结尾

序号越界时返回Paragraph range "10-" is invalid or out of bounds.

💡 优先级提示：section命中后再叠加paragraphRange或maxLength，就是"章节 + 片段"的精细组合，适合只要某章开头几句话的场景。

web_url_read 常见报错与解决

完整的排错对照表见 docs/troubleshooting.md，各限制项的默认值见 CONFIGURATION.md。

支持的内容类型一览

web_url_read按 Content-Type 智能分流（分类逻辑见 classifyContentType）：

进阶：应对反爬的浏览器求解器

若目标站有访问挑战，mcp-searxng 可配置 FlareSolverr / Byparr 浏览器求解器：先获取 cookie 与 User-Agent，再由web_url_read用该会话二次抓取。相关控制与预算（预检、超时、失败回退）见 docs/browser-solver-deployment.md 与 CONFIGURATION.md。求解器只解决"拿到会话"，不保证目标页放行，排错时请区分获取阶段与回放阶段。

相关文档与源码

• 工具参数与限制全表：docs/tools.md
• 研究工作流（搜索 + 交叉验证 + 引用）：docs/research-workflow.md
• 工具注册入口：src/index.ts
• 读取与转换主逻辑：src/url-reader.ts
• PDF 提取 worker 与常量：src/pdf-reader.ts
• URL 安全边界（私有地址拦截）：src/url-security.ts