searchio

searchio

searchio は、検索、ページの読み取り、商品検索のためのツールです。コマンドライン、Python、HTTP 経由で利用できます。人間でも AI エージェントでも使用できます。検索と読み取りに API キーは必要ありません。

AI エージェント向けクイックスタート

AI エージェントは、1 回の操作でユーザー向けに searchio をセットアップできます。以下の手順を順番に実行してください。検証の手順が成功したら終了します。

1. Docker が動作している場合は Docker を使います。 次を試してください。

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp

イメージには、フェッチ階層、Rust エンジンのサイドカー、チャレンジ階層用の Chromium を含むシステム全体が収録されています。ほかにインストール手順はありません。手順 3 に進んでください。

2. Docker がない場合は、ソースからインストールします。 Python 3.10 以降が必要です。

pip install "searchio[mcp]"
curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

pip コマンドは、PyPI から MCP サーバーを含む searchio パッケージをインストールします。curl コマンドは、Rust エンジンのサイドカーを ~/.searchio/bin/se-serve に追加します（linux、macOS、Git Bash を使用した Windows）。サイドカーは高速な tier-2 バックエンドです。なくても動作しますが、インストールをおすすめします。最新の開発ビルドを使うには、pip install "searchio[mcp] @ git+https://github.com/IOServicesLabs/searchio" を実行してください。

3. MCP サーバーをクライアントに追加します。 Claude Desktop と Cursor では、この形式の設定を使用します。

Docker：

{
  "mcpServers": {
    "searchio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/ioserviceslabs/searchio-mcp"]
    }
  }
}

ソースからインストールする場合：

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

4. 検証します。 クライアントを再起動します。「searchio を使って、東京の現在時刻をウェブ検索してください」と尋ねてください。実際の検索結果が表示されれば、セットアップは成功です。コマンドが見つからないというエラーが出た場合は、設定で指定したパスが存在しません。設定を修正して、もう一度試してください。

注。手順 3 のクライアントコマンドには、npx @ioserviceslabs/searchio-mcp も使えます。Docker が動作している場合、ランチャーは Docker イメージを起動します。Docker がない場合は、手順 2 で行ったローカルインストールを起動します。

1. インストール

Python 3.10 以降が必要です。

方法 A -- pip（1 つのコマンド）：

pip install "searchio[mcp]"
searchio-mcp        # MCP server on stdio, ready for an LLM client

searchio doctor でインストールを確認できます。Rust エンジンのサイドカーは任意です。クイックスタートの手順 2 にある curl コマンドでインストールしてください。

方法 B -- Docker（Python 不要）：

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp              # stdio MCP
docker run -p 8080:8080 ghcr.io/ioserviceslabs/searchio-mcp \
  searchio-mcp --transport sse --host 0.0.0.0 --port 8080

お使いのプラットフォーム用のビルド済みイメージがない場合は、ソースからビルドしてください。

docker build -t searchio https://github.com/IOServicesLabs/searchio.git

イメージには、Python の各階層、Rust エンジンのサイドカー、チャレンジ階層用の Chromium を含む全階層が収録されています。状態（クリアランス、セッション）は /root/.searchio のボリュームに保持されます。

docker run -i --rm -v searchio-state:/root/.searchio ghcr.io/ioserviceslabs/searchio-mcp

方法 C -- ソースから：

git clone https://github.com/IOServicesLabs/searchio.git
cd searchio
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux
pip install -e '.[mcp]'
searchio doctor

searchio doctor で、お使いのマシンで動作するフェッチ階層を確認できます。Tier 0 は通常の HTTP です。Tier 1 では TLS の偽装が追加されます。Tier 2 では、ボットをブロックするページ用に実際のブラウザーが追加されます。Tier 2 は必要になった最初のタイミングで自動的に起動します。

エンジン階層（任意・推奨）

Tier 2 は、se-serve バイナリが存在する場合、Rust 製の searchio-engine サイドカーを使用します。数ミリ秒で起動し、Chromium は必要ありません。Docker イメージにはこれが含まれています。ホストにインストールする場合は、次の 1 つのコマンドで追加できます。

curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

インストーラーはバイナリを ~/.searchio/bin/se-serve に配置し、searchio が自動的に検出します。SEARCHIO_ENGINE_BIN に任意のバイナリを指定することもできます。

MCP クライアントのセットアップ

任意の MCP クライアントで、このサーバーを指定してください。

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

Docker を使う場合は、"command": "docker", "args": ["run", "-i", "--rm", "searchio"] を使用してください。

Python を使わない場合は、npm ラッパーがバックエンドを選択します（Docker があれば Docker、なければローカルインストール）。

{
  "mcpServers": {
    "searchio": {
      "command": "npx",
      "args": ["-y", "@ioserviceslabs/searchio-mcp"]
    }
  }
}

2. 検索

searchio search "best noise cancelling headphones 2026"
searchio search "rust async runtime comparison" --intent code
searchio search "artemis mission" --domains nasa.gov
searchio search "heat pump retrofit" --k 20 --json

検索の意図を指定できます。web（デフォルト）、news、video、shopping、academic、code、forum、reference、local が使えます。クエリに site:nasa.gov を含めることもできます。

3. ページを読む

searchio read https://example.com/some/article
searchio read https://example.com/paper.pdf --chars 20000

コマンドは読み取り可能なテキストを出力します。ペイウォール、ボットチェック、JavaScript のみで構成されたページにも自動で対応します。ページを読み取れない場合は、明確な理由が表示されます。空のページが返されることはありません。

4. 商品とリスティング

searchio items "sony wh-1000xm5"                    # one row per product across retailers
searchio items "dyson v15" --domains bestbuy.com --json
searchio marketplace "ford f-150" --city seattle    # Facebook Marketplace, browser-backed

5. AI スウォームで調査する

この機能には料金がかかります。キーを 1 つ設定してください。

set ANTHROPIC_API_KEY=...            # Windows
# export ANTHROPIC_API_KEY=...       # macOS / Linux
searchio research "What changed in the EU battery regulation this year, and who is affected?"

代わりに DeepSeek を使うには、SEARCHIO_LLM_PROVIDER=deepseek と DEEPSEEK_API_KEY=... を設定してください。調査結果を含む回答が返されます。それぞれの調査結果には、ワーカーが読んだページへの引用が付いています。

6. MCP サーバーとして実行する

searchio は MCP（Model Context Protocol）サーバーとしても動作します。AI エージェントは MCP 経由でこれを呼び出します。CLI が使用するツールと同じものをエージェントも利用できます。

MCP 用の追加機能をインストールします。

pip install -e '.[mcp]'

stdio 経由でサーバーを起動します。

searchio mcp
# or
python -m searchio.mcp

HTTP 経由でサーバーを起動します。

searchio mcp --transport streamable-http --host 127.0.0.1 --port 8080 --path /mcp

6.1 MCP ツール

サーバーには次のツールがあります。

ツール	説明
search	キー不要のプロバイダーを横断した、統合済みのランキング付きウェブ検索です。
search_items	複数の小売業者の商品リストを統合し、価格を表示します。
search_local	都市周辺の Facebook Marketplace の出品情報です（ブラウザー経由）。
youtube_transcript	1 本の YouTube 動画の字幕文字起こしです。タイムスタンプ付きのセグメントと全文を返します。
read_url	ブロック耐性のある段階的な方法で、1 つの URL を読み込みます。Markdown を返します。
research	質問に対して複数ステップのリサーチスウォームを実行します（LLM キーが必要です）。
stats	段階別の処理とプロバイダーの健全性を表示します（ドメインごとに学習した段階、ブロック率）。

サーバーには 1 つのリソースもあります。searchio://health はサービスの健全性を小さな JSON オブジェクトとして返します。

6.2 検索とリサーチの支払い（x402）

MCP サーバーには支払いゲートがあります。x402 の形式を使用します。ゲートが有効な場合、課金対象のツールは、呼び出し元が支払いを行うまで X-Payment チャレンジとともに 402（Payment Required）を返します。

SEARCHIO_MCP_PAYMENT でゲートを設定します。

値	結果
``（空、デフォルト）	ゲートは開いています。課金されません。ローカル環境および開発用途向けです。
static:<token>	呼び出し元は Authorization: Bearer <token> を送信する必要があります。送信しない場合、ツールは 402 と X-Payment チャレンジを返します。

これは実際の検証サービスが使用する形式です。台帳はありません。他のユーザー向けにサーバーをホストする場合は、その前段に実際の x402 検証サービスを配置してください。検証サービスが支払いを確認した後、ツールが実行されます。これが、検索およびリサーチのクレジット向けに searchio を SwarmIO と並べてホストする方法です。

7. HTTP サーバーとして実行する

searchio serve --port 8080

エンドポイント	説明
GET /search?q=...&intent=web&k=10&domains=a.com,b.org&freshness=week&locale=de-DE	検索結果
GET /read?url=...&session=me	1 ページの読みやすいテキスト
GET /items?q=...&domains=...	商品ごとに統合された商品リスト
GET /marketplace?q=...&city=seattle	Facebook Marketplace の出品情報
GET /transcript?url=...&lang=en	YouTube の字幕文字起こし（400 動画ではない · 404 字幕なし · 451 拒否）
POST /research {"question": "..."}	AI リサーチスウォーム
GET /providers、GET /stats、GET /healthz	ステータス

エラーには実際のステータスコードを返します。不正なリクエストには 422、ポリシーで拒否された対象には 400、ボット対策の壁でブロックされたページには 451、プロバイダーで障害が発生した場合や、障害後のクールダウン中のプロバイダーしかない場合には 502 または 503 を返します。検索結果には providers_used、providers_failed、providers_skipped（サーキットブレーカーが開いているプロバイダーと、残りのクールダウン時間）が含まれます。

複数のユーザーやエージェントで 1 つのサーバーを共有する場合は、/read でそれぞれに別の session を割り当ててください。そうすれば、あるユーザーの Cookie が別のユーザーのリクエストに付与されることはありません。

8. Docker で実行する

このリポジトリの Dockerfile は、Python の各段階、Rust エンジンのサイドカー、チャレンジ対応段階用の Chromium を含む完全な段階構成をビルドします。ビルドおよび実行コマンドについては、セクション 1 のパス B を参照してください。docker compose up でも、状態ボリュームを接続した同じ構成を実行できます。

コンテナ内では、段階 2 でまずエンジンのサイドカーを使用し、実際のブラウザーが必要なページには patchright Chromium を使用します（チャレンジ対応段階）。キャッシュ、ドメインごとに学習した段階、クリアランス Cookie は searchio-state ボリュームに保存されるため、再起動後も維持されます。リサーチスウォームのキーは、セクション 10 と同じ環境変数名で設定します。

9. Python から使用する

import asyncio
from searchio.engine import Engine

async def main():
    eng = Engine()
    res = await eng.search("lithium iron phosphate battery lifespan", intent="web", k=5)
    for doc in res.docs:
        print(doc.title, doc.url)

    doc = await eng.read("https://example.com/article")
    print(doc.text[:500])

    items = await eng.find_items("sony wh-1000xm5")
    for it in items:
        print(it.title, it.price, it.url)

    await eng.close()

asyncio.run(main())

10. 設定

すべての設定は、SEARCHIO_ プレフィックスが付いた環境変数、または実行場所と同じディレクトリにある .env ファイルの行で指定します。よく変更される項目は次のとおりです。

変数	デフォルト	意味
SEARCHIO_MAX_TIER	2	0 は HTTP のみ、1 は TLS 偽装を追加、2 はブラウザーを追加
SEARCHIO_ROBOTS_POLICY	warn	enforce、warn、または off
SEARCHIO_PROXY	なし	HTTP ティア用のプロキシ URL
SEARCHIO_FACEBOOK_CITY	なし	Marketplace 検索のデフォルトの都市
SEARCHIO_CACHE_ENABLED	true	取得したページを1時間キャッシュします
SEARCHIO_STATE_DIR	~/.searchio	キャッシュ、プロファイル、クリアランスクッキーの保存場所
SEARCHIO_MCP_PAYMENT	``	MCP の支払いゲート（6.2 を参照）
SEARCHIO_MCP_BEARER	なし	MCP ゲートが確認するベアラートークン

11. 知っておくとよいこと

• 検索と閲覧にキーは不要で、料金もかかりません。有料モデルを呼び出すのは research のみです。
• このツールが認証情報を外部に送信することはありません。Marketplace などのブラウザーを使用する検索は匿名で実行されます。
• searchio providers で、すべてのソースと設定状況を確認できます。
• 問題が起きたときは、まず searchio doctor を実行してください。