blowsh-mcp

Browsh 기반 JavaScript 지원 터미널 브라우징을 위한 Model Context Protocol 서버

blowsh-mcp란?

blowsh-mcp는 Browsh(완전한 JavaScript 지원 터미널 브라우저)의 기능을 모든 AI 에이전트, IDE 에이전트 또는 MCP 클라이언트에 노출하는 Model Context Protocol(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를 한 번 실행하고 유지하며 RAM/CPU 효율적인 단일 인스턴스를 재사용하고 종료 시 깨끗하게 종료합니다.

• TTL이 있는 인메모리 렌더 캐시: 반복적인 가져오기는 다시 렌더링하지 않고 즉시 제공됩니다.

• PaaS, 클라우드, 로컬 AI 도구 및 IDE 에이전트를 위해 설계되었습니다.

링크

• Browsh CLI 브라우저 — 렌더링 엔진.

• Firefox — Browsh의 백엔드로 필요합니다.

• Model Context Protocol(MCP) 사양 — 에이전트/서버 프로토콜.

작동 방식

1. AI/에이전트가 MCP 요청을 보냅니다: fetch_web(단일 URL), search_web(쿼리), extract_links(URL) 또는 fetch_web_batch(최대 10개 URL).

2. blowsh-mcp는 Browsh를 HTTP 서버 모드로 시작하고(첫 사용 시) 이후 모든 호출에 재사용합니다.

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에 게시되며 GitHub Actions를 통해 main 푸시마다 자동으로 다시 빌드됩니다 — 호스트 측 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 포함: 모든 JavaScript 실행 후 전체 HTML 마크업. 요소 파싱, 링크 그래프 구성, 복잡한 스크래핑 등에 사용.

• type: markdown 포함: 깔끔한 Markdown 버전 — LLM 컨텍스트 청크, 의미론적 파이프라인, AI 친화적인 소비/워크플로우에 가장 적합.

• 오류는 구조화됩니다: MCP 응답은 가능한 경우 HTTP 상태를 포함하는 FetchError 메시지와 함께 isError: true를 설정합니다.

프로젝트 구조

• 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

  • 또는 릴리스 페이지에서 OS에 맞는 사전 빌드 바이너리를 사용하세요.

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는 헤드리스/HTTP 작동 중 Browsh가 사용하는 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, 20MB 제한).

• 오류는 구조화되어 있습니다: isError: true가 설정된 MCP 응답과 알 수 있을 때 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/streamable 서버가 명시적으로 구성되지 않는 한 공개적으로 노출되지 않습니다.

• 방화벽 없이 포트를 공개 웹에 노출하지 마세요.

• 비밀/구성에는 환경 변수를 사용하세요.

확장

src/tools/에 새 도구를 추가하고 src/server.ts에서 내보낸 후 문서화하세요.
AI 클라이언트는 docstring을 자동으로 발견합니다.

문제 해결

• fetchPlain이 404를 반환하거나 JS 렌더링에 실패하면: Firefox와 Browsh가 설치되어 있고 PATH에 있는지 확인하세요.

• Firefox를 찾을 수 없거나 시작에 실패하면 .env에서 BROWSH_FIREFOX_PATH를 설정하여 Firefox 설치 경로를 지정하세요.

• Browsh 포트/호스트는 고정되어 있습니다—이를 변경할 수 있는 환경 또는 CLI 설정은 없습니다.

• 최대 보안을 위해 컨테이너에서 실행하세요.

라이선스

MIT

작성자: Mohammad Reza Mokhtarabadi mmokhtarabadi@gmail.com