Clawifi

clawifi

Clawifi の公式 Python SDK、CLI、MCP サーバーです。AI エージェント向けのウェブ検索とページ読み取りを提供します。複数の検索エンジンをまとめて検索し、ページや PDF を読み取り、サイトをマッピングしてクロールし、質問への回答となる文章だけを出典付きで取得できます。これらすべてを、型付きの単一 API と MCP インターフェースで利用できます。

このパッケージは、ホスト型 Clawifi API（リリース時点のホスト型 API バージョンは 1.7.2）を利用する薄いクライアントであり、Clawifi サーバーは含まれていません。ドキュメント、料金、ステータスについては、clawifi.dev/docs · clawifi.dev/pricing · clawifi.dev/status · clawifi.dev/security をご覧ください。

ワンクリックインストール（ホスト型サーバー。お試しにキーは不要です）

どちらもホスト型リモートサーバー https://api.clawifi.dev/mcp を追加します。お試しにキーは不要です。1 日あたり 1 アドレスにつき 50 回、4 つのツールを利用できます。すべてのツールを使うには API キーを追加してください（無料キーを取得）。

インストール

pip install clawifi

API キーを取得する

clawifi signup --email [email protected] --password "a strong password"

アカウントが作成され、無料クレジット 1,000 が付与され、API キーが表示されます。次のコマンドで環境変数に設定します。

export CLAWIFI_API_KEY="clawifi_live_..."

クイックテスト

clawifi quicktest --url https://example.com

MCP クライアントを設定する

clawifi init

このコマンドは、このマシンにインストールされている MCP クライアント（Claude Code、Codex、Cursor、Claude Desktop、VS Code）を検出し、それぞれについてローカルサーバー（clawifi-mcp、stdio）とリモートサーバーのインストール用コマンドに続けて、試せる最初の呼び出しを表示します。表示のみを行い、キーを表示することはありません。表示するのは $CLAWIFI_API_KEY またはマスクされた clawifi_live_**** のみです。clawifi init --all は、検出されたクライアントと未検出のクライアントをすべて表示します。

設定ファイルを編集させるには、次のコマンドを実行します。

clawifi init --write cursor            # ~/.cursor/mcp.json, stdio entry
clawifi init --write cursor --remote   # ~/.cursor/mcp.json, remote entry
clawifi init --write claude-desktop    # claude_desktop_config.json, stdio entry

--write は、変更前に確認を求め、まず既存のファイルを <file>.bak-<timestamp> にコピーします。Claude Code、Codex、VS Code にはそれぞれ独自のインストールコマンドがあり、init が表示します。

たとえば、Claude Code の場合は次のとおりです。

# local (stdio)
claude mcp add --env CLAWIFI_API_KEY=$CLAWIFI_API_KEY --transport stdio clawifi -- clawifi-mcp
# remote
claude mcp add --transport http clawifi https://api.clawifi.dev/mcp --header "Authorization: Bearer $CLAWIFI_API_KEY"

MCP サーバーとして使用する

ローカル MCP サーバーは次のコマンドで実行します。

clawifi-mcp

CLAWIFI_API_KEY は環境変数から読み取られます。clawifi mcp config は最小限の設定を表示します。すべてのツールにタイトルと、MCP のヒントである readOnlyHint、destructiveHint、idempotentHint、openWorldHint が付いています。破壊的なツールはありません。

課金対象のツール（fetch、scrape、extract、map_site、crawl、search_free）では、共通オプションをパラメーターとして指定し、その他の API フィールドは options に指定します。options はリクエスト本文に統合されます。dry_run は受け付けません。呼び出しの料金を確認するには estimate ツールを使用してください。ツールで宣言されていない引数は無視せず、拒否されます。

リモート MCP

Clawifi はホスト型 MCP サーバーも実行しているため、インストールは不要です。

• URL：https://api.clawifi.dev/mcp（ストリーミング可能な HTTP）
• 認証：Authorization: Bearer <your key>、または X-Clawifi-Api-Key: <your key> ヘッダー

旧ホストの api.clawifi.qzz.io（API と /mcp）も引き続き利用できるため、CLAWIFI_API_BASE=https://api.clawifi.qzz.io や既存のリモート設定を変更する必要はありません。

キーがない場合、リモートサーバーではキー不要の 4 つのツール、search_free、fetch_url、scrape_url、map_site を、アドレスごとに 1 分あたり 12 回、1 日あたり 50 回まで利用できます。キーがあれば、すべてのツールを利用できます。

クレジット

呼び出しは操作ごとに課金されます（通常のフェッチは 1 クレジット、ブラウザーのレンダリングは 3 クレジット、クロールはページごとに 1 クレジットなど）。clawifi.dev/pricing をご覧いただくか、キー不要で現在の料金表を出力してください。

clawifi credits

代わりに、credits MCP ツールと client.credits() で、ご自身の利用状況と残高を確認できます。

Python SDK として使用する

from clawifi import Clawifi

client = Clawifi()  # reads CLAWIFI_API_KEY from the environment
page = client.fetch("https://example.com")
print(page["success"])

clawifi.AsyncClawifi として非同期クライアントも利用できます。

search_content は上位の検索結果を検索して読み取ります。デフォルトでは簡潔な結果を返し、full=True を指定すると出力全体を返します。

results = client.search_content("agent memory benchmarks", full=True)

レスポンスは API が返す内容のまま返されるため、published_at、modified_at、fetched_at などのフィールドは変更されずに渡されます。

見積もり（ホスト型 API 1.7.0 以降）

quote = client.estimate("fetch", url="https://example.com")
# {"dry_run": true, "route": "POST /fetch", "estimate": {"minimum": ..., "maximum": ..., "raises": [...]},
#  "balance": ..., "would_402": ..., "would_429": ..., "binding_limit": ..., "charged": 0}
client.crawl("https://example.com", max_pages=50, dry_run=True)

estimate() と dry_run=True は、fetch、scrape、extract、map、crawl、search_free、search_content で動作します。最初のドライランの前に、クライアントは /product/manifest で API のバージョンを確認します。1.7.0 より古い API は dry_run を無視して呼び出しを実行（および課金）するため、クライアントは ClawifiDryRunUnsupportedError を発生させ、何も送信しません。1.7.0rc1 などのプレリリースは、1.7.0 より古いバージョンとして扱われます。

dry_run は True の場合にのみ送信され、JSON のブール値 true としてのみ送信されます。通常の呼び出し、または dry_run=False では、リクエスト本文に dry_run キーは含まれません。また、ブール値ではない値を指定すると、何も送信される前に TypeError が発生します。ドライランに対応していないルートで dry_run キー（false も含む）を指定すると、API は 422 を返すため、schema_assist は dry_run=False を削除し、dry_run=True を拒否します。

estimate MCP ツールを使うと、エージェントからも同様に実行できます：estimate(operation="fetch", args={"url": "https://example.com"})。

レート制限

429 が返された場合、Retry-After ヘッダーの秒数を示す retry_after と、どの制限に達したかを示す limit_scope（details.limit_scope から取得）を持つ ClawifiAPIError が発生します。再試行可能な呼び出しでは、最大 10 秒の Retry-After が経過するまで待ってから再試行します。それより長い場合は、直ちにエラーが返されます。

MCP ツール

ツール	説明
fetch	URL を 1 つ取得し、抽出したコンテンツを返します。query を指定すると、その質問に回答する箇所のみを返します。
scrape	ソースに応じたルーティングで URL をスクレイピングし、構造化されたコンテンツを返します。query を指定すると、その質問に回答する箇所のみを返します。
search_free	無料枠のウェブ検索を実行し、結果を返します。
extract	URL から構造化データを抽出します。
map_site	シード URL を起点に、サイト内で検出可能な URL をマッピングします。
crawl	シード URL から非同期クロールを開始し、ポーリング用の crawl_id を返します。
estimate	fetch、scrape、extract、map、crawl、search_free、search_content の呼び出しについて、実行や課金をせずに料金を見積もります（ホスト型 API 1.7.0 以降）。
get_crawl	クロールの現在のステータスと結果を取得します。
create_job	課金対象の操作を非同期ジョブとして作成し、ポーリング用の job_id を返します。
get_job	ジョブの現在のステータスと結果を取得します。
account	認証済みアカウントのプロフィールとプランを取得します。
credits	認証済みアカウントのクレジット使用量と残高を取得します。
list_history	認証済みアカウントの過去のリクエストを一覧表示します。
list_monitors	認証済みアカウントに設定された Evidence Monitor のチェック項目を一覧表示します。

ドキュメント

API リファレンス、MCP ツール一覧、CLI コマンドリファレンスについては、clawifi.dev/docs をご覧ください。

License

MIT