blowsh-mcp

面向支持 JavaScript 的终端浏览器 Browsh 的模型上下文协议服务器

blowsh-mcp 是什么？

blowsh-mcp 是一个 Model Context Protocol（MCP）服务器，它将 Browsh——一个完全支持 JavaScript 的终端浏览器——的强大能力暴露给任何 AI 代理、IDE 代理或 MCP 客户端。该项目允许你的 AI 获取并渲染任何现代网页（包括需要 JavaScript 的页面），并以易于解析的纯文本、HTML 或 Markdown 形式接收结果。

助记符：“blowsh” = Browsh 驱动的 MCP 服务器。

Related MCP server: Crawlbase MCP

关键特性

• fetch_web 工具： 统一工具，可在完整 JS 渲染后提取可读的纯文本、HTML 或 Markdown。支持 CSS selector 提取、max_chars 输出上限以及 wait_ms JS 稳定轮询。

• search_web 工具： 通过渲染的搜索引擎（DuckDuckGo HTML，Bing 作为备用）发现页面——返回带 URL 和摘要的排名结果。

• extract_links 工具： 从任意 JS 渲染后的页面列出超链接（文本 + 绝对 URL），便于导航跟随。

• fetch_web_batch 工具： 一次调用获取最多 10 个 URL，并对每个 URL 进行错误隔离。

• SSRF 防护： 拒绝指向环回、私有、链路本地或保留地址（经 DNS 解析）的请求，保护服务端浏览器。

• 面向 AI 优化的工具文档： 输入、输出和示例用例专为无缝的代理自动化而设计。工具会抛出带有 HTTP 状态码的结构化错误（MCP 响应中的 isError）。

• 稳健的 Browsh 管理： 启动一次 Browsh，保持其运行，复用低内存/低 CPU 的单例，退出时优雅关闭。

• 带 TTL 的内存渲染缓存： 重复获取无需重新渲染即可即时返回。

• 专为 PaaS、云、本地 AI 工具和 IDE 代理设计。

链接

• Browsh CLI 浏览器 — 渲染引擎。

• Firefox — Browsh 所需的后端。

• Model Context Protocol (MCP) Specification — 代理/服务器协议。

工作原理

1. AI/代理发出 MCP 请求：fetch_web（单个 URL）、search_web（查询）、extract_links（URL）或 fetch_web_batch（最多 10 个 URL）。

2. blowsh-mcp 以 HTTP 服务器模式启动 Browsh（首次使用时），并在后续所有调用中复用。

3. blowsh-mcp 使用 X-Browsh-Raw-Mode: PLAIN（用于文本）、DOM（用于 HTML）请求 Browsh 的原始输出，或获取 HTML 后转换为 Markdown。

4. 页面（在完整执行 JS 后）以终端纯文本、丰富 HTML DOM 或干净 Markdown 形式返回——AI/代理根据下游处理需求选择输出类型。

5. 结果缓存在内存中（TTL），因此重复获取即时完成；每个请求在到达浏览器之前都会经过 SSRF 检查。

快速开始（Docker — 预构建镜像）

镜像发布到 GitHub Container Registry，并在每次 main 推送时通过 GitHub Actions 自动重建——无需宿主机上的 Firefox/Browsh/html2markdown：

docker pull ghcr.io/mokhtarabadi/blowsh-mcp:latest
docker run --rm -i ghcr.io/mokhtarabadi/blowsh-mcp:latest

-i 标志是必需的：MCP 服务器通过 stdin/stdout 使用 JSON-RPC 通信。请保持其 交互式并管道传输请求，或将你的 MCP 客户端指向它（参见 下方的 AI 客户端配置）。

示例用法

来自 Claude、Cursor 或任何支持 MCP 的代理：

{
  "tool": "search_web",
  "params": { "query": "bitcoin price today", "max_results": 5 }
}
// → Ranked results with URLs + snippets → feed top URL to fetch_web

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "plain" }
}
// → Returns readable plain text (live price as text table, etc)

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "markdown", "selector": "main", "wait_ms": 3000 }
}
// → Markdown of <main> only, after JS settles ("# Bitcoin Price\n\n| Time | Price | ...")

{
  "tool": "extract_links",
  "params": { "url": "https://example.com", "limit": 20 }
}
// → [{"text": "Learn more", "url": "https://iana.org/domains/example"}, ...]

{
  "tool": "fetch_web_batch",
  "params": { "urls": ["https://a.com", "https://b.com"], "type": "markdown" }
}
// → Per-URL results; a failing page never fails the batch

AI 接收：

• 使用 type: plain：纯可读文本（表格、列表、主体内容；非常适合 NLP/摘要或终端上下文摄入）。

• 使用 type: html：完整 HTML 标记，在所有 JavaScript 执行之后。用于元素解析、链接图构建、复杂抓取等。

• 使用 type: markdown：干净的 Markdown 版本——最适合 LLM 上下文块、语义管道以及 AI 友好的消费/工作流。

• 错误是结构化的：MCP 响应设置 isError: true，并带有包含 HTTP 状态（可用时）的 FetchError 消息。

项目结构

• src/server.ts — 暴露工具的 MCP 服务器。

• src/browshManager.ts — 启动、监控、关闭 Browsh。

• src/tools/fetchWeb.ts — fetchWeb 工具实现（plain、html、markdown；selector/max_chars/wait_ms）。

• src/tools/searchWeb.ts — search_web（DuckDuckGo HTML + Bing 备用解析器）。

• src/tools/extractLinks.ts — extract_links（从渲染后的 DOM 中提取超链接）。

• src/tools/fetchWebBatch.ts — fetch_web_batch（多 URL，按 URL 进行错误隔离）。

• src/tools/html2markdownManager.ts — html2markdown CLI 的包装器。

• src/ssrf.ts — SSRF 防护（阻止私有/环回/保留目标）。

• src/cache.ts — 内存 TTL 渲染缓存。

• src/extract.ts — 主要内容提取、选择器辅助、截断。

• src/errors.ts — FetchError + 消息格式化。

• README.md — 本文件。

• Dockerfile — 多阶段容器（构建 TS，打包 Firefox、Browsh、html2markdown）。

• .github/workflows/docker-publish.yml — CI/CD：在 main/v* 上构建并发布镜像到 ghcr.io。

• .env — 配置覆盖。所有选项请参阅 .env.example。

安装

要求：

• Node.js >= 20.18

• 已安装 Firefox 并加入 PATH

• 已安装 Browsh CLI 并加入 PATH

• 已安装 html2markdown CLI 并加入 PATH

  • 在 Debian/Ubuntu 上，使用以下命令安装：

    wget -O /tmp/html2markdown.deb "https://github.com/JohannesKaufmann/html-to-markdown/releases/download/v2.5.2/html2markdown_2.5.2_linux_amd64.deb"
    sudo apt-get install -y /tmp/html2markdown.deb
    rm /tmp/html2markdown.deb

  • 或者使用适用于你的操作系统的预构建二进制文件，见 releases 页面。

喜欢 Docker？完全跳过宿主机安装——多阶段镜像打包了 Firefox、Browsh 和 html2markdown。最快的路径是使用已发布的镜像 （ghcr.io/mokhtarabadi/blowsh-mcp:latest，参见 快速开始）； 如果需要自己构建：

docker build -t blowsh-mcp:latest .
docker run --rm -i blowsh-mcp:latest

git clone https://github.com/mokhtarabadi/blowsh-mcp.git
cd blowsh-mcp
npm install
npm run build

运行 MCP 服务器

构建完成后，使用以下命令启动服务器：

node dist/server.js

如果你的构建输出不同，请将 dist/server.js 替换为正确的路径。

根据需要创建 .env 文件进行配置。例如：

MCP_TRANSPORT=stdio
BROWSH_FIREFOX_PATH=/usr/bin/firefox-esr
HTML2MARKDOWN_PATH=html2markdown
CACHE_TTL_MS=300000
BROWSH_REQUEST_TIMEOUT_MS=30000
ALLOW_PRIVATE_URLS=false
NODE_ENV=production

• BROWSH_FIREFOX_PATH 允许你自定义 Browsh 在无头/HTTP 操作期间使用的 Firefox 可执行文件。

• HTML2MARKDOWN_PATH 允许你指定 html2markdown 二进制文件的自定义路径（默认：PATH 中的 html2markdown）。

• CACHE_TTL_MS、BROWSH_REQUEST_TIMEOUT_MS 和 ALLOW_PRIVATE_URLS 分别调整渲染缓存、每次请求超时和 SSRF 防护。

• Browsh 的 HTTP 端口/主机不可配置。

项目文档

本 README 是面向用户的入口点；面向代理的规则位于 AGENTS.md 中，在任何实现之前必须阅读。

工具 API

返回

• type: plain：终端风格、已执行 JS 的可读文本（或错误字符串）。

• type: html：JS 执行后的 HTML 标记字符串（或错误字符串）。使用 selector 时，仅返回匹配元素的 HTML。

• type: markdown：对主要内容或所选元素进行 Markdown 转换（或错误字符串）。保留链接、标题、列表和页面结构，以便 AI 友好地使用上下文。

• type: pdf：从 PDF 文档中提取的纯文本（通过 pdftotext，最大 20 MB）。

• 错误是结构化的：MCP 响应包含 isError: true 以及带有 HTTP 状态（已知时）的 FetchError 消息（绝不静默返回空字符串）。

环境变量

通过 .env（自动加载）或环境设置这些变量：

AI 引导的工具选择

• 从 search_web 开始： 要 发现 页面，运行查询并选择最佳结果 URL；然后获取它们。

• 对单个页面使用 fetch_web： 当需要用于摘要/分类的快速可读输出时使用 plain；解析元素、链接或表格时使用 html；需要 LLM 友好的上下文块时使用 markdown。添加 selector/max_chars/wait_ms 以保持令牌高效并获得稳定、相关的内容。

• 在深度爬取之前使用 extract_links： 以较低成本跟随导航，而不是获取完整的 DOM。

• 对多个来源使用 fetch_web_batch： 一次调用替代 N 次往返；每个 URL 的失败相互隔离。

错误处理： 工具会抛出 FetchError，MCP 返回 isError: true 并附带可操作的消息——无效协议、SSRF 拦截、选择器不匹配、HTTP 状态码和渲染失败都不会静默发生。

MCP 协议：AI 客户端配置

在配置你的 AI 客户端（Claude、Cursor 等）之前，你必须

1. 安装依赖：    npm install

2. 构建项目：    npm run build

3. 从编译输出启动 MCP 服务器：    node dist/server.js

适用于 Claude Desktop 或 Cursor 的示例配置：

{
  "mcpServers": {
    "blowsh": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {}
    }
  }
}

适用于 opencode（项目 opencode.json）的示例配置：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blowsh": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "ghcr.io/mokhtarabadi/blowsh-mcp:latest"],
      "enabled": true,
      "timeout": 120000
    }
  },
  "permission": { "blowsh_*": "allow" }
}

Docker 形式不需要宿主机侧二进制文件；镜像捆绑了 Firefox、Browsh 和 html2markdown。保存后重启 opencode（配置在启动时仅加载一次）。

优雅关闭

blowsh-mcp 捕获 SIGINT/SIGTERM 并确保 Browsh 被干净地终止——不会留下孤立的浏览器进程。

安全与注意事项

• 服务器在本地运行 Browsh，并通过 HTTP localhost 进行获取。

• SSRF 防护： 默认情况下，fetch_web/search_web/extract_links/fetch_web_batch 拒绝解析到回环、私有、链路本地或保留 IP 范围的 URL（通过 DNS 检查）。设置 ALLOW_PRIVATE_URLS=true 可禁用——不推荐。

• 除非显式配置了 MCP HTTP/流式服务器，否则不会公开暴露。

• 切勿在未设置防火墙的情况下将端口暴露到开放网络。

• 使用环境变量存储密钥/配置。

扩展

在 src/tools/ 中添加新工具，在 src/server.ts 中导出它们，并编写文档。
AI 客户端会自动发现 docstrings。

故障排除

• 如果 fetchPlain 返回 404 或无法渲染 JS：请检查 Firefox 和 Browsh 是否已安装并位于 PATH 中。

• 如果找不到 Firefox 或启动失败，请在 .env 中设置 BROWSH_FIREFOX_PATH 以指定 Firefox 安装的完整路径。

• Browsh 的端口/主机是固定的——没有环境变量或 CLI 设置可以更改它们。

• 为获得最大安全性，请在容器中运行。

许可证

MIT

作者： Mohammad Reza Mokhtarabadi mmokhtarabadi@gmail.com