clean-markdown

clean-markdown-mcp

一个 MCP 服务，可将任意 URL 转换为整洁、适合大模型使用的 Markdown——没有广告、导航栏、Cookie 横幅或脚本。

专为 RAG 工作流和 AI Agent 打造，因为输入中有垃圾，输出也会是垃圾。

Give it:  https://en.wikipedia.org/wiki/Markdown
Get back: # Markdown

          Markdown is a lightweight markup language for creating
          formatted text using a plain-text editor...

安装

npm install -g clean-markdown-mcp

与 Claude Desktop 搭配使用

将以下内容添加到你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clean-markdown": {
      "command": "npx",
      "args": ["-y", "clean-markdown-mcp"]
    }
  }
}

重启 Claude Desktop，然后让它 “将 https://example.com 抓取为 Markdown。”

在 Cursor、Windsurf 或任何其他 MCP 客户端中使用方法相同——将其指向 clean-markdown-mcp 命令即可。

提供的工具

scrape_url

参数	类型	说明
url	string	要抓取的页面。必须以 http:// 或 https:// 开头。
includeLinks	boolean	在 Markdown 中保留超链接。默认值为 true。设为 false 可获得更简洁的文本。
renderJs	boolean	对于由 JavaScript 构建的网站，先在真实浏览器中加载页面。默认值为 false。需要 Playwright——见下文。

返回页面标题、来源、字数和整洁的 Markdown。

清理原理

1. 抓取——超时时间为 20 秒，大小上限为 5 MB，并在每次重定向时验证目标地址。
2. 清理——使用 Mozilla Readability 处理内容。它是 Firefox 阅读视图背后的引擎，可提取正文并移除导航、侧边栏、广告和评论区。
3. 转换——使用 Turndown 将内容转换为 GitHub 风格的 Markdown，并保留标题、列表、表格和代码块。

如果页面不符合文章结构，则会改为清理 <body>，而不是直接失败，因此你仍能获得可用文本。

JavaScript 密集型网站（可选）

有些网站会在加载后使用 JavaScript 构建内容。对于这些网站，普通抓取几乎无法返回内容。要处理这类网站，请安装一次 Playwright：

npm install playwright && npx playwright install chromium

然后传入 renderJs: true。对于这类页面，效果差异显著：

模式	结果
默认	约 3 个词——只有导航链接
renderJs: true	约 190 个词——完整内容

Playwright 不是此软件包的依赖项，因此常规安装依然轻量、快速。如果未安装 Playwright，renderJs 会返回一条清晰的提示，告知你如何启用它。

安全性

抓取器会拒绝私有地址、环回地址和链路本地地址，包括 169.254.169.254 等云元数据端点，并重新验证每次重定向的目标地址。这一点很重要，因为 MCP 服务运行在你的机器上，可以访问你的本地网络。

需要大规模抓取？

此软件包一次在本地处理一个页面。如需批量抓取、托管式 JavaScript 渲染以及无需运行任何基础设施的按页付费 API，可通过托管 Actor 使用相同的引擎：

https://apify.com/perforated_hummingbird/url-to-markdown

已知限制

• 有些网站会屏蔽自动化流量。这是网站的策略，并非此处的缺陷。
• 非 UTF-8 页面可能会显示乱码。
• 不会遵循 robots.txt——你需要自行负责如何使用它。

本地开发

npm install
npm run build
node dist/try.js https://example.com          # quick test
node dist/try.js https://example.com --render # with JS rendering

许可证

MIT