LionScraper MCP + CLI + HTTP API (Python)

LionScraper MCP + CLI + API サービス（Python）

简体中文

• ウェブサイト: lionscraper.com
• PyPI: プロジェクト lionscraper

これは何ですか？

LionScraper は、ウェブページからリスト、記事、リンク、画像などを収集できるブラウザー拡張機能です。この PyPI パッケージは、その拡張機能と連携するブリッジを、次の3つの方法で提供します。

• MCP（lionscraper-mcp）：AI アプリ（Cursor など）を接続し、チャット内でモデルがスクレイピングツールを呼び出せるようにします。
• CLI（lionscraper）：拡張機能と同じローカル HTTP/WebSocket ポートを介して、ターミナルから daemon、scrape、ping を実行します。
• HTTP API：デーモンの実行中に、ループバック JSON HTTP（/v1/...）経由で同じツールを呼び出します。MCP や CLI のフロントエンドを使わずに、スクリプト、サービス、または任意の HTTP クライアントから利用できます。

実際のスクレイピング処理は拡張機能で実行されます。このパッケージは接続して、リクエストを転送します。

始める前に

1. ブラウザー：Chrome または Edge（拡張機能が実際にサポートしているものを使用してください）。
2. LionScraper 拡張機能：ブラウザーのストアからインストールして有効にします（ストアによって掲載名が異なる場合があります）。
   • Chrome：Chrome ウェブストア — LionScraper
   • Microsoft Edge：Edge アドオン — LionScraper
3. Python：お使いのマシンに 3.10 以降が必要です。まだインストールされていない場合は、Python のウェブサイトからインストーラーをダウンロードし、画面の指示に従ってください（Windows では、インストーラーに選択肢がある場合、Python を PATH に追加するオプションにチェックを入れてください）。
4. MCP の場合：MCP をサポートする AI アプリ（Cursor、Trae など）。
5. HTTP API の場合：CLI と同じブラウザー、拡張機能、デーモンを使用します。curl、fetch、または任意の HTTP クライアントで http://127.0.0.1:$PORT にアクセスしてください（以下のHTTP API（ローカル REST）を参照）。

このパッケージは、デーモンへのアウトバウンド HTTP および WebSocket のプローブに aiohttp を使用します。Chrome/Edge が検出されず、拡張機能が接続されていない場合、ping / scrape* はサーバー側の HTTP フォールバック（ページ内 JavaScript は使用しません）を利用できます。

インストール（pip）

このパッケージは PyPI で lionscraper として公開されています。

pip install -U lionscraper

仮想環境（推奨）を使用するか、システムのインタープリターへのインストールを避けたい場合は pip install -U --user lionscraper を実行してください。

2つのコマンドがインストールされ、組み合わせて3種類の連携方法（MCP、CLI、HTTP API）を利用できます。

コマンド	役割
lionscraper-mcp	AI アプリ向けの軽量な MCP サーバー（stdio）
lionscraper	CLI：daemon、stop、scrape、ping、…（HTTP API を提供するプロセスも実行します）

インストール後に lionscraper-mcp が PATH に見つからない場合は、スクリプトのフルパス（たとえば、仮想環境の Scripts/ または bin/ 内）を使用するか、以下の MCP での python -m lionscraper 形式を使用してください（通常の pip install -U lionscraper が必要です）。

---

MCP（AI アプリケーション）

AI アプリに MCP を追加する

例では、lionscraper-mcp が PATH 上にあることを前提としています（UI によって異なります）。MCP JSON では、すべての env の値は文字列です。

最小構成（組み込みのデフォルトを使う場合は env を省略します。PORT のデフォルトは 13808 で、拡張機能のブリッジポートと一致させる必要があります）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp"
    }
  }
}

env の完全な例（不要なキーは削除してください。ほとんどのキーでは、空文字列は「未設定」と同じように動作します）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp",
      "env": {
        "PORT": "13808",
        "TIMEOUT": "120000",
        "LANG": "en-US",
        "TOKEN": "",
        "DAEMON": ""
      }
    }
  }
}

• PORT：HTTP + WebSocket の待ち受けポートです。デフォルトは 13808 で、拡張機能のブリッジポートと一致させる必要があります。
• TIMEOUT：ポートを解放するために前のインスタンスを待つ時間（ミリ秒）です。タイムアウトすると強制的に引き継ぎます。デフォルトは 120000 です。0 にすると、すぐに強制します。
• LANG：ツールの説明と stderr ログの言語です（en-US、zh-CN、または en_US.UTF-8 のような POSIX 形式）。
• TOKEN：デーモンと共有するベアラートークンです。空の場合、Authorization ヘッダーは送信されません。
• DAEMON：thin MCP からの lionscraper daemon の自動起動を無効にするのは 0 の場合のみです。空、またはその他の値はキーを省略した場合と同じです（自動起動が許可されます）。

設定を適用するには、MCP またはアプリを再起動してください。

lionscraper-mcp が PATH 上にない場合

pip install -U lionscraper の後、python -m lionscraper で同じルーティングを実行できます。モジュール名の後に引数がない場合は stdio 経由の thin MCP が選択され、追加の引数（--debug を含む）がある場合は CLI が使用されます。例：

{
  "mcpServers": {
    "lionscraper": {
      "command": "python",
      "args": ["-m", "lionscraper"]
    }
  }
}

パッケージのインストールに使用したものと同じ python 実行ファイルを使用してください（システムによっては python3）。

ブラウザー拡張機能のポートを一致させる

1. LionScraper の設定／オプションを開きます。
2. ブリッジポートを PORT と同じ値に設定します（例：13808）。
3. 必要に応じて、拡張機能の Reconnect を使用するか、拡張機能を再読み込みするか、ブラウザーを再起動してください。

日常的な使用（MCP）

1. 拡張機能を有効にし、必要な対象ページを開いたままにします。
2. 「LionScraper が接続されているか確認して」や「このページからリスト／記事／メールアドレス／電話番号／リンク／画像をスクレイピングして」のように、自然言語で依頼します。
3. 未接続またはタイムアウトが表示された場合は、接続確認を再試行し、PORT が一致していることを確認します。

MCP ツール（概要）

サーバーは拡張機能の機能に対応するツールを登録します。名前と形式は、MCP クライアントがモデルに表示するものです。

ツール	用途（概要）
ping	拡張機能が接続され、登録されていることを確認します
scrape	構造を自動検出します（リスト、テーブルなど）。ページネーションに対応しています
scrape_article	記事本文（例：Markdown）とメタデータを取得します
scrape_emails	ページ上のメールアドレスを取得します
scrape_phones	電話番号を取得します（構造化形式）
scrape_urls	ハイパーリンクの URL を取得します
scrape_images	画像の URL と基本的なメタデータを取得します

パラメーター： 各フィールドの完全な JSON スキーマは、クライアントに表示されるツール定義と、リリースに対応したドキュメントに記載されています。ここに重複して記載すると、すぐに古くなります。MCP を呼び出す際は、AI アプリ内のツール一覧／説明を使用してください。

MCP リソース／プロンプト

軽量な MCP プロセス（lionscraper-mcp）は、ツールに加えてリソースとプロンプトを公開します。

• リソース：安定した URI にある静的な Markdown です。例：lionscraper://guide/connection（PORT の整合、ping のトラブルシューティング）、lionscraper://guide/when-to-use-tools（シナリオに応じて WebFetch／curl／wget より LionScraper を優先）、lionscraper://guide/cli（ターミナル CLI）、lionscraper://reference/tools、lionscraper://reference/common-params。クライアントはリソースを一覧表示／読み取りしてコンテキストに取り込みます。リソースはstdio プロセス内で提供され、デーモンの HTTP パスは不要です（拡張機能がオフラインの場合でも動作します）。ループバック HTTP コントロールプレーン（/v1/...）については、以下のHTTP API（ローカル REST）を参照してください（MCP リソース URI ではありません）。
• プロンプト：ワークフローテンプレートです（例：ping-then-scrape、multi-URL、scrape_article、prefer_lionscraper_scraping、拡張機能のトラブルシューティング）。クライアントはプロンプトを一覧表示／取得します。UI はホストによって異なります（Cursor、Trae、…）。

コピーはツールのメタデータと同じく、LANG（例：zh-CN）に従います。

---

CLI（ターミナル）

lionscraper コマンドは、MCP と同じスタックのターミナルフロントエンドです。lionscraper daemon は PORT（デフォルトは 13808）で、HTTP（CLI と軽量な lionscraper-mcp プロセスが使用）および WebSocket（拡張機能が使用）をリッスンします。PORT（および任意の TOKEN）を拡張機能のブリッジポートと MCP の設定に合わせてください。AI チャットを開かずに、スクリプト、CI、または一度限りの簡単な実行に CLI を使用できます。

CLI は http://127.0.0.1:$PORT 上のデーモン HTTP API と通信します（デフォルトポートは 13808 で、拡張機能と同じです）。--api-url を指定しない場合、scrape または ping の実行時に、可能であればローカルデーモンが自動起動します。

よく使うコマンド：

lionscraper --help
lionscraper daemon              # keep running; HTTP + WebSocket on PORT
lionscraper stop                # stop daemon on configured PORT
lionscraper ping
lionscraper scrape -u https://www.example.com
lionscraper scrape --method article -u https://www.example.com
# Shorthand: lionscraper -u https://www.example.com   → same as scrape

--method は、デーモンが実行するツールを選択します（デフォルトは scrape）。選択肢：scrape、article、emails、phones、urls、images。-u／--url を繰り返して指定すると、1 回の実行で複数の URL を渡せます。

環境変数に PORT（および任意の TOKEN）を設定し、CLI を拡張機能および MCP に合わせてください。デーモンのベース URL がデフォルトと異なる場合は、--api-url http://127.0.0.1:PORT を使用してください。バイナリで指定できるすべてのフラグを確認するには、lionscraper --help を実行してください。

スクレイピング：パラメーターと詳細な例

以下のフラグは拡張機能に転送されます（**--bridge-timeout-ms**を除きます。このフラグは、CLI がブリッジ上で待機する時間の上限のみを設定します）。実際の動作は、引き続き拡張機能のバージョンに依存します。

出力と接続

フラグ	説明
--format json or pretty	1 行の JSON、またはインデント付きの JSON（デフォルトは json）
--raw	ツールから返されたテキストブロックを、再フォーマットせずに出力します
-o / --output <file>	結果を標準出力ではなくファイルに書き込みます

タイミングと負荷

フラグ	説明
--delay <ms>	ページの読み込み後、スクレイピングを開始するまで待機します（動的コンテンツ向け）
--timeout-ms <ms>	拡張機能側の URL ごとのタイムアウト
--bridge-timeout-ms <ms>	この CLI → デーモン呼び出しの最大待機時間
--scrape-interval <ms>	複数の URL の処理を開始する際の間隔
--concurrency <n>	複数 URL の実行における並行処理数のヒント
--scroll-speed <px>	全体的なスクロール速度（拡張機能の仕様に従います）
--max-pages <n>	リスト形式の scrape におけるページネーションの上限

遅延読み込み／無限スクロール（ツールのペイロード内の waitForScroll に対応）

フラグ	説明
--wait-scroll-speed <px>	スクロール時の 1 ステップあたりのピクセル数
--wait-scroll-interval <ms>	スクロールの各ステップ間の待機時間
--wait-max-scroll-height <px>	スクロール距離の最大値（任意）
--scroll-container <selector>	スクロール可能なコンテナのセレクター（任意）

ロケール

フラグ	説明
--lang zh-CN or en-US	メッセージ／拡張機能の UI 文字列に使用する言語のヒント

追加ペイロード

フラグ	説明
--include-html + true / false	対応している場合、meta にページ全体の HTML を含めるよう要求します
--include-text + true / false	対応している場合、meta にページ全体のプレーンテキストを含めるよう要求します

メソッド固有のフィルター（例。全項目については --help を参照してください）

• メールアドレス（--method emails）：--email-domain、--email-keyword、--email-limit
• 電話番号（--method phones）：--phone-type、--phone-area-code、--phone-keyword、--phone-limit
• URL（--method urls）：--url-domain、--url-keyword、--url-pattern、--url-limit
• 画像（--method images）：--img-min-width、--img-min-height、--img-format、--img-keyword、--img-limit

ブラウザー自動化の任意のヒント（拡張機能が対応している場合）：--auto-launch-browser、--no-auto-launch-browser、--post-launch-wait-ms。

---

例 A — ページネーション、遅延、スクロール補助を使ったリスト／テーブルのスクレイピング

lionscraper scrape \
  -u https://www.example.com/items \
  --max-pages 5 \
  --delay 800 \
  --timeout-ms 90000 \
  --bridge-timeout-ms 180000 \
  --wait-scroll-speed 400 \
  --wait-scroll-interval 350 \
  --lang zh-CN \
  --format pretty \
  -o items.json

• --max-pages：このジョブでリストを蓄積する「ページ」を最大 5 ページに制限します。
• --delay：抽出を開始する前に、ページの読み込み後さらに待機します。
• --timeout-ms / --bridge-timeout-ms：拡張機能側と CLI 側の待機時間です。サイトの応答が遅い場合やページが重い場合は、両方の値を大きくしてください。
• --wait-scroll-*：スクレイピングの前に遅延読み込みの行が表示されるよう、ゆっくりスクロールします。
• -o / --format pretty：確認しやすい JSON ファイルとして保存します。

---

例 B — HTML スナップショットを任意で含めた記事本文

lionscraper scrape --method article \
  -u https://www.example.com/blog/post-1 \
  --include-html true \
  --timeout-ms 120000 \
  --format json

• --method article：scrape_article ツールに対応します（拡張機能が提供する場合、Markdown 形式の本文とメタデータを取得します）。
• --include-html true：対応している場合、結果の meta に追加の HTML を含めるよう要求します（ペイロードが大きくなります）。

---

例 C — フィルターを使った複数ページのメールアドレスと URL の取得

lionscraper scrape --method emails \
  -u https://www.example.com/contact \
  --email-domain example.com \
  --email-keyword support \
  --email-limit 30 \
  --format pretty

lionscraper scrape --method urls \
  -u https://www.example.com \
  -u https://www.example.com/docs \
  --url-domain example.com \
  --url-limit 200 \
  --scrape-interval 500

• メールアドレスのフラグ：ドメイン、キーワードで絞り込み、取得数に上限を設定します。
• 2 つの -u 値：1 回の呼び出しで 2 つの URL を処理します。--scrape-interval により、タスクの開始間隔を空けます。

---

例 D — サイズ／形式フィルターを使った画像の取得

lionscraper scrape --method images \
  -u https://www.example.com/gallery \
  --img-min-width 240 \
  --img-min-height 240 \
  --img-format webp \
  --img-limit 40 \
  -o gallery-images.json

• 拡張機能がこれらのフィールドに対応している場合、小さなサムネイルと WebP 以外のアセットを除外します。--img-limit は返される項目数の上限を設定します。

---

HTTP API（ローカル REST）

ベース URL： http://127.0.0.1:$PORT（デフォルトは 13808）。127.0.0.1 のみで待ち受けます。そのポートに拡張機能が接続され、デーモンが待ち受けている必要があります（このパッケージの他の部分と同じプロセスモデルです）。

メソッド	パス	レスポンス（成功時）
GET	/v1/health	{ "ok", "identity", "bridgePort", "sessionCount" }
POST	/v1/daemon/shutdown	{ "ok": true } の後、デーモンが終了します
POST	/v1/tools/call	ツールの結果 JSON（以下を参照）

それ以外はすべて → 404 { "ok": false, "error": { "code": "NOT_FOUND", "message": "Not found" } }。

認証： デーモンに TOKEN 環境変数が設定されている場合、すべてのリクエストに Authorization: Bearer <TOKEN> が必要です。設定されていない場合はヘッダーを省略してください。

POST /v1/tools/call

• ヘッダー： Content-Type: application/json。ストリーミングの場合は、Accept: application/x-ndjson も指定します。
• 本文：

{ "name": "<tool>", "arguments": { }, "progressToken": "<optional>" }

フィールド	意味
name	次のいずれか：ping、scrape、scrape_article、scrape_emails、scrape_phones、scrape_urls、scrape_images
arguments	ツールのペイロード。空の場合は省略するか、{} を指定します
progressToken	任意の文字列または数値。Accept: application/x-ndjson の場合、本文は NDJSON です（type: "progress" の行の後に、最後に type: "result" または type: "error" が続きます）

arguments（JSON キー）

ping のみ： lang（"en-US" | "zh-CN"）、autoLaunchBrowser（ブール値）、postLaunchWaitMs（数値、3000～60000）は任意です。

すべてのスクレイピング系ツール（scrape、scrape_article、scrape_emails、scrape_phones、scrape_urls、`scrape_images）で共通：

キー	型	制約・注記
url	string | string[]	必須 — 1 つの URL または URL の配列
lang	"en-US" | "zh-CN"	任意
delay	number	任意、≥ 0
timeoutMs	number	任意、≥ 1000
bridgeTimeoutMs	number	任意、≥ 1000
includeHtml	boolean	任意
includeText	boolean	任意
scrapeInterval	number	任意
concurrency	number	任意
scrollSpeed	number	任意
autoLaunchBrowser	boolean	任意
postLaunchWaitMs	number	任意、3000～60000
waitForScroll	object	任意。設定する場合は scrollSpeed と scrollInterval が必須です。maxScrollHeight、scrollContainerSelector を含めることもできます

scrape のみ： maxPages（数値、≥ 1）は任意です。

任意の filter オブジェクト（対応するツールのみ）：

name	filter のプロパティ
scrape_emails	domain、keyword、limit（≥ 1）
scrape_phones	type、areaCode、keyword、limit（≥ 1）
scrape_urls	domain、keyword、pattern、limit（≥ 1）
scrape_images	minWidth、minHeight（≥ 0）、format、keyword、limit（≥ 1）

不明な name、不正な JSON、またはスキーマ違反 → 400 { "code": "BAD_REQUEST", ... }。不正な Bearer 認証情報 → 401 UNAUTHORIZED。ツールのクラッシュ → 500 INTERNAL。

200 の本文： { "content": [ { "type": "text", "text": "..." } ], "isError"?: boolean }。

例（PORT=13808）

curl -sS "http://127.0.0.1:13808/v1/health"
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" \
  -d '{"name":"ping","arguments":{}}'
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" \
  -d '{"name":"scrape_article","arguments":{"url":"https://www.example.com","timeoutMs":120000}}'
# With TOKEN on the daemon:
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"ping","arguments":{}}'

---

よくある質問（平易な説明）

Q：拡張機能が接続されない、またはスクレイピングに失敗しますか？

• 拡張機能は有効になっていますか？
• MCP の PORT（または CLI の環境変数）は、拡張機能の ブリッジポートと完全に一致していますか？
• 1 台のマシンで、互いに競合する複数の MCP／CLI の設定を使用しないでください。

Q：AI アプリに多数の「ツール」が表示されています。拡張機能が接続されているということですか？

必ずしもそうとは限りません。ツールによって確認できるのは AI → MCP サーバーの接続だけです。拡張機能も同じポートに接続し、登録されている必要があります。

Q：CLI でデーモンに接続できないと表示されます。

別のターミナルで lionscraper daemon を起動するか、PORT／--api-url を修正してください。

Q：独自の HTTP クライアントからスクレイピングを操作したいのですが？

デーモンと拡張機能で同じ PORT を使用し、HTTP API（ローカル REST）の説明に従って name と arguments を指定し、POST /v1/tools/call を実行してください。GET /v1/health で、リスナーが LionScraper であることを確認できます。

ライセンス

MIT（PyPI の lionscraper パッケージと同じです）。