Hugging Face smolagents + Scrapeless MCP: PythonでAIウェブスクレイパーを構築する

Ava Wilson

Expert in Web Scraping Technologies

17-Jul-2026

TL;DR:

Hugging Faceエージェントは1つのMCPエンドポイントから21のライブウェブツールを取得します。 ToolCollection.from_mcpをhttps://api.scrapeless.com/mcpに指し示すと、smolagentsはCodeAgentブラウザ制御、ページスクレイピング、Google検索およびトレンドを手に入れますが、レンダリング、プロキシルーティング、そしてアンチ検出はサーバーサイドに留まります。
ホスティングパスは完全なPythonです。 x-api-tokenヘッダー付きのストリーミングHTTPが、ローカルサーバープロセスを置き換えます — Node.jsは不要で、pip install "smolagents[mcp]"のみです。
ツールのインターフェースはモデルより前に機能します。 scrape_markdownへの単純な関数呼び出しは、きれいなマークダウンとしてライブページを返します — このガイドのデモページは4,249文字です — なので、Scrapeless APIキーだけで配線をテストできます。
AIスクレイパーはセレクタではなく意味で抽出します。 エージェントはマークダウンを読み取り、要求したフィールドを返しますので、CSSセレクタースクリプトを壊すサイトの再設計は通常、何もコストがかかりません。
唯一の追加前提はモデルキーです。 ツールリスト、直接ツール呼び出し、エージェント構築はすべてワンなしで実行できますが、推論ラウンドトリップにはHugging Faceトークンまたは別のサポートプロバイダーが必要です。
無料で始められます。 app.scrapeless.comで無料プランのAPIキーを作成してください。

この統合が可能にすること

セレクタベースのスクレイパーは、ターゲットページが決して変わらないことに賭けるものであり、その賭けはしばしば失敗します。AIスクレイパーは異なるアプローチを取ります: ページをクリーンなテキストとして取得し、言語モデルにフィールドを抽出させ、今週価格がどのdivにあるかを気にしないようにします。

smolagentsはHugging Faceの小さなエージェントライブラリで、エージェントはツールを呼び出すためにPythonを記述し、JSONツール呼び出しを発行しません。自身にはライブウェブにアクセスするための方法がありません。それがModel Context Protocolの役割です: Model Context Protocol仕様は、サーバーが任意のクライアントがリストし呼び出せる型付きツールをどのように広告するかを定義しています。このプロトコル自体が新しい場合は、MCPとは何か、どのように機能するのかの入門編が概念をカバーしています。

二つを結びつければ、数十行のPythonでプログラム可能なAIスクレイパーが得られます: smolagentsは推論ループを提供し、Scrapeless MCPサーバーは取得、レンダリング、検索を呼び出し可能なツールとして提供します。このガイドでは、そのスクレイパーを段階的に構築し、Scrapelessキーだけで動作する部分を正確に示します。

なぜScrapeless MCPなのか

Scrapeless MCPサーバーは、スクレイピングインフラを21の型付きツールとして公開し、重い作業はあなたのプロセスではなく、サーバー上で行われます。scrape_html、scrape_markdown、scrape_screenshotは異なる形状で単一ページをキャプチャします。16のbrowser_*ツールは、スクレイピングブラウザ上でクラウドブラウザセッションを操作します — これは自社開発のChromiumによるアンチ検出クラウドブラウザで、エージェントがクリック、タイプ、スクロールする必要がある仕事に対応します。google_searchとgoogle_trendsは探索をカバーします。

このビルドにおいて重要な3つの特性:

1つのキー、ホスティングされたトランスポート。 プラットフォームの残りを駆動するのと同じScrapeless APIキーがMCPエンドポイントを認証します。あなたのPythonプロセスはブラウザやNodeサーバーを起動しません。
モデルフリーのテスト可能性。 ツールはリストされ、LMMが循環にいない状態で実行されるため、統合はエージェントの推論を通じてデバッグされるのではなく、一層一層証明できます。
マークダウン優先の抽出パス。 ページのマークダウンキャプチャは、生のHTMLサイズの一部に過ぎないため、抽出あたりのトークンが少なく、モデルが読みやすいノイズも少なくなります。scrape_markdownは正確にそれを返します。

同じエンドポイントは、あなたのスタックがそれであればLangChainにも接続します — LangChain + Scrapeless MCPガイドはアダプター側から同じ表面をサポートしています。

前提条件

Python 3.10以上 — このガイドで実行されたのはPython 3.12を使用しました。
ダッシュボードからのScrapeless APIキー — 開発者ドキュメントではキーの作成とエンドポイント参照がカバーされています。
最終エージェントの往復にのみ必要: Hugging Faceのトークン（またはsmolagentsがサポートする任意のモデルプロバイダーの認証情報）。それ以前のすべてのステップは、トークンなしで実行されます。

インストールと設定

1つのパッケージに1つの追加で、エージェントライブラリとMCPクライアントの配管が導入されます。これらのバージョンは、このガイドが書かれたものです — smolagents 1.26.0、mcp 1.27.1、mcpadapt 0.1.20：

bash Copy

pip install "smolagents[mcp]==1.26.0"

スクリプトがソースコードではなく環境から読み取れるように、キーをエクスポートします：

bash Copy

export SCRAPELESS_API_KEY="sk_your_key_here"

ストリーミングHTTPを介して接続し、ツールをリストアップ

接続は辞書であり、設定ファイルではありません。ToolCollection.from_mcpは、基盤となるストリーミングHTTPクライアントと同じパラメータを受け入れるため、エンドポイントURL、トランスポート名、および認証ヘッダーが1つのリテラルで渡されます：

python Copy

# connect_and_list.py — Scrapeless MCPサーバーとのハンドシェイク、ツールをリスト
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    names = sorted(tool.name for tool in tc.tools)
    print(f"ツール数: {len(names)}")
    print("\n".join(names))

コンテキストマネージャは接続ライフサイクルを管理します: エントリ時にMCPハンドシェイクを実行し、終了時にクリーンに切断します。1つのパラメータに関して言及する価値があります: MCPツール仕様により、サーバーは結果をプレーンテキストまたは構造化コンテンツとして返すことができ、Scrapelessツールはテキストを返すため、明示的にstructured_output=Falseを渡してください。smolagents 1.26はパラメータが省略された場合に警告を出します。なぜなら、そのデフォルトは将来のリリースで切り替わる予定だからです。

正しくハンドシェイクが行われると、ツール数: 21というメッセージがプリントされ、続いて名前が表示されます: 16のbrowser_*ツール、google_search、google_trends、scrape_html、scrape_markdown、scrape_screenshot。

標準入出力ルートも存在し、ローカルサーバープロセスを起動したいクライアントのためのものです — 異なるライフサイクルの背後にいる同じ21のツール：

json Copy

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": { "SCRAPELESS_KEY": "sk_your_key_here" }
    }
  }
}

Python専用のビルドの場合、ストリーミングHTTPが短い道です: pip以外に何もインストールする必要はなく、何も実行しておく必要はありません。

無料プランのAPIキーを取得: app.scrapeless.com

モデルが関与する前にscrape_markdownを呼び出す

コレクション内のすべてのツールは呼び出し可能なsmolagentsのToolオブジェクトであるため、スクレイピング層を直接エクササイズできます — エージェントまたはモデルキーは関与しません：

python Copy

# call_tool.py — 1つのMCPツールをプレーンな関数呼び出しとして実行
import json
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    tools = {tool.name: tool for tool in tc.tools}
    raw = str(tools["scrape_markdown"](url="https://quotes.toscrape.com/"))
    # ホスティングされたツールは、"Response:"行の後にページをJSON引用された文字列として返します —
    # それをデコードしてマークダウン自体を取得します。
    body = raw.split("\n\n", 1)[1] if raw.startswith("Response:") else raw
    text = json.loads(body) if body.startswith('"') else body
    print(f"scrape_markdownは{text:,}文字のマークダウンを返しました")
    print(text[:160])

引用のデモサイトに対してこれは4,249文字のマークダウンを返し、ページタイトルと最初の引用から始まります — ページのク chromeが取り除かれた可読テキストです。その単一の呼び出しがスクレイパーのすべてのフェッチ層です。それ以降は解釈です。

ツールをCodeAgentに添付する

コレクションをエージェントにバインドするのは1つのコンストラクタであり、モデル呼び出しが発生する前に機能します。エージェントオブジェクトは、すべてのMCPツールを名前でfinal_answerの隣にインデックスします：

python Copy

# attach_agent.py — MCPツール面をsmolagentsのCodeAgentに渡す
import os

from smolagents import CodeAgent, InferenceClientModel, ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    model = InferenceClientModel(model_id="Qwen/Qwen2.5-72B-Instruct")
    agent = CodeAgent(tools=[*tc.tools], model=model, add_base_tools=False)
    print(sorted(agent.tools.keys()))

add_base_tools=Falseは、ツールボックスをMCPツールとエージェントの組み込みfinal_answerに制限します。ページを取得するだけのスクレイパーの場合、さらに絞り込むことができます — 例えば、tools=[t for t in tc.tools if t.name == "scrape_markdown"]と渡すと、モデルは物理的にブラウザセッションや不必要な検索コールに迷い込むことができません。ツールボックスが小さくなることは、システムプロンプトが小さくなり、モデルの間違った方向に進む可能性も減少します。

プロンプト駆動型の使用：AIスクレイパーの実行

抽出ステップはプロンプトであり、パーサーではありません。エージェントにどのページを読むか、どのフィールドを返すかを指示し、エージェントはscrape_markdownを呼び出し、結果を読み取り、回答を組み立てます — smolagentsは各ツールを型付き入力でモデルに説明し、同じ構造をJSONスキーマ仕様が機械可読なフィールド制約のために定義しています。

注意：この最後のステップは、このガイドの唯一の前提条件のギャップです — エージェントの往復にはモデルプロバイダーが必要です。実行する前に、Hugging Faceのトークン（または他のsmolagentsがサポートするプロバイダーを設定）でHF_TOKENを設定してください。上記のすべてのブロックは、Scrapelessキーのみで実行されます。

python Copy

# run_scraper.py — モデルの往復（HF_TOKENまたは他のプロバイダーが必要）
result = agent.run(
    "Call scrape_markdown on https://quotes.toscrape.com/ and return a JSON array "
    "of the quotes on the page. Each item must have exactly these keys: "
    "text (string), author (string), tags (array of strings). "
    "Return only the JSON array, no commentary."
)
print(result)

プロンプトの形状は出力の形状を制御します。正確なキーとタイプを指定し、「JSON配列のみ」を要求し、1回の実行につき1ページを維持することで、json.loadsできる出力を得て、下流で検証できます。ページにフィールドが欠けている場合、エージェントに値を作り出すのではなくnullを使用するよう指示します — モデルは、そう指示されない限り、自信を持って隙間を埋めます。

戻ってくるもの

取得レイヤーからは、文字列としてのマークダウンが得られます：ページタイトルは見出しとして、リンクテキストはブラケット内に保持され、本文は読み取り順に表示されます。引用サイトからの4,249文字のキャプチャは次のように始まります：

text Copy

# [Quotes to Scrape](https://quotes.toscrape.com/)

[Login](https://quotes.toscrape.com/login)

“The world as we have created it is a process of our thinking.

エージェントの実行からは、プロンプトが強制した契約に基づくものが得られます — ここでは、ページ上の各引用ごとに{text, author, tags}オブジェクトのJSON配列です。配置の価値は、ターゲットサイトがクラス名を変更した日にも現れます：マークダウンは依然として引用を含み、プロンプトはフィールドの名前を依然として指定し、スクレイパーはセレクターに基づくスクリプトが何も返さないのに対し、同じスキーマを返します。

結論

統合は3つの小さな動きで行われます：ToolCollection.from_mcpをホストされたエンドポイントにポイントし、直接scrape_markdownを呼び出して取得レイヤーを確認し、ツールをCodeAgentにバインドしてプロンプトで抽出を行います。各レイヤーはそれ自身でテスト可能で、最後のものだけがモデルキーを必要とし、従来のスクレイパーで最も壊れやすい部分 — パース — はモデルが吸収します。

エージェントに実際のウェブサーフィスを与える準備はできていますか？

MCPエンドポイントは、Scrapelessプラットフォームの他の部分と同じAPIキーで認証されます — プランと含まれるボリュームは価格ページで確認できます。app.scrapeless.comで無料プランにキーを作成すると、上記のハンドシェイクスクリプトは1分以内に21のツールを出力します。

FAQ

Q: AIスクレイパーとは何ですか？

AIスクレイパーとは、抽出ステップに言語モデルを使用するスクレイパーです。従来のスクレイパーは、特定のページ構造にフェッチとパースを結びつけますが、AIスクレイパーはページをテキストとして取得し、モデルに名前付きフィールドを返すように求めるため、レイアウトの変更に対しても機能します。

Q: Scrapelessツールを呼び出すためにHugging Faceトークンは必要ですか？

いいえ。ツールのリスト、scrape_markdownの直接呼び出し、CodeAgentの構築は、Scrapeless APIキーだけで認証されます。Hugging Faceトークン（または他のプロバイダーのキー）は、正確に1つのこと、つまりagent.run()の推論の往復に必要です。

Q: ストリーミングHTTPまたはstdioで接続すべきですか？

PythonプロジェクトにはストリーミングHTTPを使用してください：ローカルプロセスを必要とせず、ヘッダーで認証されます。stdioトランスポート（npx -y scrapeless-mcp-server、環境変数SCRAPELESS_KEYを通じて認証）は、サーバープロセスを自分で管理するデスクトップMCPクライアントに適しています。どちらのトランスポートも同じツールサーフェスを公開します。
Q: エージェントは21のツールの代わりに1つのツールだけを使用できますか？

はい。エージェントを構築する前にコレクションをフィルタリングします — tools=[t for t in tc.tools if t.name == "scrape_markdown"] — そしてモデルはそのツールしか見ません。単一目的のスクレイパーには、この形が推奨されます：システムプロンプトが縮小され、モデルは意図しないブラウザセッションを開始することができなくなります。

Q: JavaScriptが重いページやボット対策のチャレンジの背後にあるページはどうですか？

レンダリングはサーバーサイドで行われるため、Pythonのコードは変更されません。scrape_htmlとscrape_markdownはJavaScriptの実行が必要なページを扱い、browser_*ツールはクリックや入力が必要なフローのために完全なクラウドブラウザセッションを提供します。プロキシルーティングと対検出は、エージェントが考慮すべきものではなく、管理されたサービスの一部です。

Q: どのモデルがsmolagentsと連携しますか？

ライブラリがサポートする任意のプロバイダー。InferenceClientModelはHugging Face推論プロバイダーを通じて提供されるモデルをカバーし、ライブラリはOpenAIModel、AzureOpenAIModel、AmazonBedrockModel、LiteLLMModel、およびTransformersModelのようなローカルバックエンドも提供します — 現在のリストについてはsmolagentsモデル参照を参照してください。MCP側はモデルに依存しません：ツールは、どのモデルがそれらを推論しても同じように見えます。

Q: AIエージェントでスクレイピングすることは合法ですか？

すべてのスクレイパーと同じルールが適用されます：公開ページのみを収集し、ターゲットサイトの利用規約とロボット指令を尊重し、ボリュームを制限し、適用されるプライバシー法の下で個人データを取り扱います。エージェントは抽出がどのように行われるかを変更しますが、収集できる内容を変更するわけではありません — 疑問がある場合は、作業負荷を拡大する前に法律顧問に相談してください。

Scrapelessでは、適用される法律、規制、およびWebサイトのプライバシーポリシーを厳密に遵守しながら、公開されているデータのみにアクセスします。このブログのコンテンツは、デモンストレーションのみを目的としており、違法または侵害の活動は含まれません。このブログまたはサードパーティのリンクからの情報の使用に対するすべての責任を保証せず、放棄します。スクレイピング活動に従事する前に、法律顧問に相談し、ターゲットウェブサイトの利用規約を確認するか、必要な許可を取得してください。