blowsh-mcp

Browshを使ったJS対応ターミナルブラウジングのためのModel Context Protocolサーバー

blowsh-mcpとは？

blowsh-mcpは、完全にJavaScriptに対応したターミナルブラウザであるBrowshのパワーを、あらゆるAIエージェント、IDEエージェント、MCPクライアントに公開するModel Context Protocol (MCP) サーバーです。このプロジェクトにより、AIはJavaScriptを必要とするものを含む最新のWebページを取得・レンダリングし、解析しやすいプレーンテキスト、HTML、Markdownとして結果を受け取ることができます。

記憶のための語呂合わせ: “blowsh” = Browshを搭載したMCPサーバー。

Related MCP server: Crawlbase MCP

主な機能

• fetch_web ツール: 完全なJSレンダリング後に、読みやすいプレーンテキスト、HTML、またはMarkdown抽出のための統合ツール。CSS selector 抽出、max_chars 出力上限、wait_ms JS安定待機ポーリングに対応。

• search_web ツール: レンダリングされた検索エンジン（Bingフォールバック付きDuckDuckGo HTML）でページを発見 — URLとスニペット付きのランキング結果。

• extract_links ツール: ナビゲーション追従用に、任意のJSレンダリングページからハイパーリンク（テキスト + 絶対URL）を一覧表示。

• fetch_web_batch ツール: 1回の呼び出しで最大10URLを取得、URLごとにエラーを分離。

• SSRFガード: ループバック、プライベート、リンクローカル、予約済みアドレスへのリクエスト（DNS解決後）を拒否し、サーバー側ブラウザを保護。

• AI最適化ツールドキュメント: シームレスなエージェント自動化のために設計された入力、出力、図解付きユースケース。ツールはHTTPステータスコード付きの構造化エラーをスローします（MCP応答の isError）。

• 堅牢なBrowsh管理: Browshを一度起動して稼働を維持し、RAM/CPU負荷の低いシングルトンを再利用、終了時にグレースフルシャットダウン。

• TTL付きインメモリレンダリングキャッシュ: 繰り返しのフェッチは再レンダリングなしですぐに提供。

• PaaS、クラウド、ローカルAIツール、IDEエージェント向けに設計。

リンク

• Browsh CLI Browser — レンダリングエンジン。

• Firefox — Browshのバックエンドとして必要。

• Model Context Protocol (MCP) Specification — エージェント/サーバープロトコル。

動作の仕組み

1. AI/エージェントがfetch_web（単一URL）、search_web（クエリ）、extract_links（URL）、またはfetch_web_batch（最大10URL）のMCPリクエストを行います。

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経由、上限20 MB）。

• エラーは構造化されています: 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 回のラウンドトリップの代わりに 1 回の呼び出しで済みます。失敗は 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/ストリーミング可能サーバーが明示的に設定されている場合を除き、公開は行われません。

• ファイアウォールなしでポートをオープンな Web に公開しないでください。

• シークレットや設定には環境変数を使用してください。

拡張

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