crawlgraph-mcp

crawlgraph-mcp

CrawlGraph と Common Crawl のスナップショットを使用してバックリンクを調査する、5 つの MCP ツールです。backlinks、backlink_changes、gap_analysis、 gap_outreach_targets、releases を利用できます。アウトリーチツールは調査候補を特定します。メッセージの送信や連絡先の作成は行いません。

認証プロファイルを選択する

接続先	認証情報	ツールプロファイル
npm / ローカル stdio	お持ちの CRAWLGRAPH_API_KEY（cg_live_…）	レガシー
https://crawlgraph.com/mcp	Authorization ヘッダー内のお持ちの API キー（Bearer cg_live_…）	レガシー
https://crawlgraph.com/mcp/connectors	Authorization ヘッダー内のアカウント連携済み OAuth アクセストークン	有効な場合、制限付きディレクトリプロファイル

レガシーの /mcp は Smithery の ?apiKey=… と、Base64 JSON の ?config=… 形式も受け付けます。ヘッダーの認証情報が最優先され、次に apiKey、最後にパックされた config の順で使用されます。Authorization ヘッダーを優先してください。コネクターエンドポイントは API キー、クエリ認証情報、パックされた設定を拒否します。OAuth トークンが公開 /api/v1 API に送信されることはありません。

ディレクトリへの登録承認と、実際の Claude/OpenAI との互換性確認はまだ完了していません。Verified への掲載やロゴの使用は主張していません。このチェックアウトのソースバージョンは 0.4.0 です。このバージョンが現在の npm またはホスト版のバージョンを示すものではありません。DEPLOY.md にリンクされた運用者向け手順書で、各配布版を個別に確認してください。

API キーの設定：npm / stdio とレガシー HTTP

CrawlGraph の API オンボーディングからキーを取得してください。無料キーの取得手続きではキーがメールで送信されますが、アカウントへのサインインは行われません。

Claude Desktop / Claude Code では、クライアントの MCP 設定に次の内容を記述してください。

{
  "mcpServers": {
    "crawlgraph": {
      "command": "npx",
      "args": ["-y", "crawlgraph-mcp"],
      "env": {
        "CRAWLGRAPH_API_KEY": "cg_live_your_key_here"
      }
    }
  }
}

Cursor、Windsurf、Cline、Zed でも、同じコマンドと環境変数の設定を使用します。ストリーミング可能な HTTP クライアントでは、それぞれのベアラー API キーを使って https://crawlgraph.com/mcp に接続できます。特定のソース機能を利用する前に、ホスト版の tools/list 応答を確認してください。

ローカル stdio の設定	必須	デフォルト
CRAWLGRAPH_API_KEY	ツールの実行に必須。遅延して解決されます	—
CRAWLGRAPH_BASE_URL	省略可能。レガシー REST アダプターでのみ使用	https://crawlgraph.com

アカウントのリンク：OAuth コネクター

運営者が審査済みサービスを有効にしたら、既存の CrawlGraph アカウントを使用して https://crawlgraph.com/mcp/connectors に接続し、元の接続ブラウザーでサインインして同意を承認します。アカウントの作成は OAuth の対象外です。アカウントが必要な場合は、開示されているオンボーディングフローに従った後、戻ってサインインをリクエストしてください。メールで送信された API キーだけではログインセッションになりません。

発行者は https://crawlgraph.com、正確なリソースは https://crawlgraph.com/mcp/connectors、唯一のスコープは crawlgraph:read です。パブリッククライアントは、認可コードと S256 PKCE を使用し、token_endpoint_auth_method=none を指定します。登録時に認証方式が省略された場合は none に正規化され、SDK が生成したシークレットは破棄されます。コンフィデンシャルクライアント方式とメタデータドキュメントの取得はサポートされていません。コールバックは、運営者が承認した HTTPS URL と完全に一致する必要があります。OpenAI のコールバックは実際のポータルから取得してください。このリポジトリでは、推測したコールバックを提供しません。

認可とコード交換では、正確なリソース値が必要です。コード交換時に redirect_uri が指定されている場合は、保存済みのコールバックと完全に一致する必要があります。省略した場合は、そのコールバックが引き続き使用されます。リフレッシュ時にリソースとスコープを省略すると、元の付与内容が引き継がれます。PKCE は、クライアント、リソース、リダイレクト、スコープのチェックと併せて、アトミックなコード交換中にバックエンドで検証されます。

アカウント接続管理を使用して、付与とリフレッシュファミリー全体を切断し、取り消します。付与とリフレッシュファミリーが有効な間は、期限切れのアクセストークンをリフレッシュできます。付与が取り消された場合、または期限切れになった場合は、再接続が必要です。ディスカバリー、OAuth、イントロスペクションの停止時は、再リンクを要求せずに 503 を返します。実行時の停止時は、再リンクのメタデータを含めず、HTTP 200 の MCP 結果内で安全なツールエラーを返します。ツール実行中の取り消しは、結果メタデータの mcp/www_authenticate を通じて通知されます。リフレッシュトークンのローテーションには再試行猶予がありません。同時に再利用するとファミリーが取り消され、トークン応答が失われた場合は再接続が必要になることがあります。コミットされた可能性のある処理の後に 503 が返された場合、コードまたはリフレッシュトークンが未使用であることは保証されません。

クォータとディレクトリツール

どちらの認証プロファイルも、アカウントの UTC カレンダー月ごとのカウンターを共有します。無料アカウントでは、バックリンク呼び出し 15 回、ギャップジョブ 0 回です。現在有料アクセスがあるアカウントでは、バックリンク呼び出し 1,000 回、ギャップジョブ 50 回です。有料対象となる条件は、バックエンドの現在のエンタイトルメントルールに従います。リリース一覧の取得では、リサーチクォータを消費しません。backlink_changes はバックリンクカウンターを共有します。

ディレクトリの入力とコスト：

ツール	引数	コスト
backlinks	domain、limit?、sort?（authority または hosts）、release_id?	バックリンク呼び出し 1 回
backlink_changes	domain、limit?、from_release?、to_release?	バックリンク呼び出し 1 回
gap_analysis	my_domain、competitor_domains[]（1～5 件）、limit?、job_id?	新規送信：ギャップジョブ 1 回。ポーリング／再開：0 回
gap_outreach_targets	ギャップの入力に加えて、include_platforms?、enrich_authority_top?	新規送信：ギャップジョブ 1 回。オプションで追加のバックリンク呼び出し N 回
releases	limit?	0 回

ディレクトリ一覧のデフォルトは 20 件、最大は 100 件です。構造化データ、テキスト、メタデータを含む、シリアライズ後の CallToolResult 全体の UTF-8 サイズ上限は 65,536 バイトです。出力がさらにクリップされた場合は crawlgraph/output メタデータで開示され、元の観測合計、ソース上限、クォータ計算、来歴、ジョブハンドルが保持されます。大規模なエクスポートにはアカウント／API のインターフェースを使用してください。 Gap ツールのポーリングは、90 秒のツール予算内で最大 75 秒間行われます。保留中の結果には job_id と正規化されたリクエストが含まれます。そのハンドルとクエリを使って同じツールを再開してください。再接続後は、同じ所有者に対する有効な新しい許可でも再開できます。ポーリングで Gap ジョブが消費されることはありません。タイムアウト、キャンセル、ネットワーク切断、またはワーカーの古さを理由に、代替ジョブを自動的に送信してはいけません。受け付けられたジョブは、まだ完了する可能性があります。キャンセルすると、それ以降のポーリングは停止します。受け付けられた送信は引き続き課金対象です。応答が失われた場合や形式が不正な場合は、消費量をゼロと断定せず、消費量不明として報告します。

Node は、サイズ上限のある JSON テレメトリを stderr に書き込みます。ディレクトリツールの各呼び出しでは、内部生成された相関 ID、固定のツール名（または unknown）、最終エンベロープのステータス、isError、許可リストにある主要および部分的なエラーコード、レイテンシ、トランスポートのフレーミングを除いた最終シリアライズ済み UTF-8 結果の正確なサイズを記録します。既知の課金対象呼び出し数と消費量不明のカテゴリは、最終エンベロープから取得します。保留中のキャンセルと、部分的な失効を伴う完了結果は、それぞれ固有のステータスとエラーフィールドを保持します。HTTP／OAuth エラーでは、固定のルートカテゴリ、ステータス、許可リストにあるコード、および応答ごとに個別の相関 ID のみを記録します。ログ記録の失敗によって応答が変わることはありません。ログには、引数、ドメイン、結果、ジョブ／アカウント／許可／クライアント／ソースの ID、呼び出し元のリクエスト ID、例外テキスト、URL、ヘッダー、設定、認証情報を含めません。

OAuth ソースの許可判定では、IPv6 アドレスをローカルバケットキー内でのみ /64 ごとにグループ化します。マップされた IPv4 アドレスは、対応する IPv4 形式と同じバケットを使用します。プライベート RPC には、引き続き正規化済みで検証された完全なイングレスソースを渡します。サイズ上限に達したバケットマップは、稼働中のウィンドウを削除せずにフェイルクローズします。バックエンドは独自のポリシーを引き続き適用します。

アウトリーチでは、競合他社との重複、権威性、ドメインに基づくバックエンドのランキングが維持されます。プラットフォームフィルターの件数は、返されたバックエンドサンプルのみを対象とします。エンリッチメントのデフォルトは 0 です。保持されたターゲットに対する追加のバックリンク呼び出しを最大 N 回行うには、enrich_authority_top=N（0～5）を明示的に指定してください。部分的な失敗が発生した場合も、完了済みの結果、項目ごとの来歴、実際に確認できた課金額、最後に確認されたクォータ、消費量不明の情報は保持されます。検証済みジョブでは、証明されたリリースをエンリッチメントに使用します。レガシージョブでは来歴を null のままにし、検索に使用したリリースを個別に記録します。

レガシーツールは元のフィールドとデフォルト値を保持します。backlinks の公開 API でのデフォルトは 1,000 行、最大は 10,000 行です。outreach の enrich_top はデフォルトが 10、最大が 25 で、エンリッチメントごとにバックリンク呼び出しを 1 回行います。レガシーの Gap ツールは、既存の 90 秒のウィンドウ内で送信とポーリングを行い、ディレクトリの job_id 入力はありません。クォータの使用量を見積もる前に、選択したプロファイルを確認してください。

結果の解釈

Common Crawl は定期的な観測データであり、リンクのリアルタイム監視ではありません。リリースの来歴が示されていても、現在そのページが対象へのリンクを掲載しているとは限りません。新しいスナップショットで参照元ドメインが見つからなかった場合も、観測されなかったことを意味するだけで、実際に削除された証拠ではありません。比較できない場合は、変更がゼロの場合とは異なります。不明な合計数やソース上限による下限は、完全な空の結果とは異なります。Gap の来歴は実行時に保存され、その後のポーリングでも保持されます。証明のない古いアーティファクトは legacy_unverified として報告され、リリース ID は null になります。参照元ドメインの重複は調査候補を示唆するものであり、サイト運営者があなたのことを一度も聞いたことがないことを示すものではありません。

調査プロンプトの例：

mine.example と a.example、b.example のバックリンクギャップを調べてください。保留中の場合は、再送信せず、返されたジョブを再開してください。任意の権威性エンリッチメントを提案する前に、来歴、上限、クォータの使用量を報告してください。

開発と検証

npm install
npm run build
node --test tests/*.test.mjs

ビルドでは TypeScript のチェックも行われます。個別の lint スクリプトは設定されていません。 テストでは、インストール済みの SDK、ローカルの HTTP フィクスチャ、偽のプライベート／パブリックバックエンド応答を使用します。ループバックソケットをバインドする権限が必要ですが、本番環境の認証情報やプロバイダーへの実際のアクセスは必要ありません。Node のフィクスチャでは、バックエンドの SQLite トランザクション、クォータの分離、クエリの固定は検証できません。これらは別途実施する crawlback バックエンドの HTTP テストと、完全なリリースゲートで確認します。

実装の参照先：HTTP インターフェース、 OAuth ルーター、プロバイダー、 プライベートバックエンドクライアント、 ディレクトリツール、レガシーサーバー。

ライセンス

MIT