CREHQ Location Intelligence

CREHQ MCP サーバー

Model Context Protocol サーバーで、CREHQ のライブ位置情報インテリジェンス REST APIを、Claude やその他の AI エージェント向けのネイティブツールに変換します。エージェントに 「Chipotle は次にどこへ出店すべきですか？」、「この施設はどのホテルチェーンに属していますか？」、「この住所にはこれまで誰が入居していましたか？」、*「Aspen Dental の信用シグナルは何ですか？」*と尋ねると、フランチャイズおよび複数店舗展開ブランド、個々の店舗、FDD 財務情報、信用シグナル、店舗レベルのテナント履歴を網羅した、CREHQ の正規の複数ソースで検証済みのデータベースに基づいて実際に回答できます。データベースには、政府記録、フランチャイズ関連の届出、ブランドが公開したデータが含まれます。

これは、CREHQ の既存の本番 API（https://crehq.com/wp-json/crehq/v1）を薄くラップしたものです。データを保存したり、サーバー側で何かを変更したりすることはありません。API キーで認証し、呼び出しを転送します。

---

提供する機能（33 ツール）

アップグレード／ペイウォールへの誘導

• crehq_request_upgrade — サンドボックスユーザーが、信用シグナル、FDD／Item 19、サイト選定基準、不動産要件、連絡先、情報源の来歴、変更履歴、一括ダウンロード、ホワイトスペース、共同テナント情報、サイトのタイムラインなどのプレミアムデータを求めた場合に使用します。無料のサンドボックスキーでは、CREHQ にアップグレードの意向を記録し、データが存在しないと言う代わりに、明確なアップグレード方法をユーザーに案内します。
• crehq_intelligence_preview — Pro セルフサービスキー向けです。月に1回利用できる、制限付きインテリジェンスプレビューのクレジットを消費し、生のプレミアムテーブルや再配布権を公開せずに、範囲を限定したエビデンスフレームを返します。

事業体の関連付け

• crehq_resolve_entity_affiliation — 施設の URL、名称、住所から、ホテル、レストラン、小売、ヘルスケア、銀行、自動車ディーラー、EV 充電施設など、さまざまな立地カテゴリーにわたる、エビデンスに裏付けられた関連状況、正規ブランド、運営会社、親会社を特定します。有効な結果には、ブランドあり、独立系、商業施設ではない、未解決が含まれます。有料アクセスが必要な場合、応答には正確な決済 URL と CREHQ のインテント ID が保持されます。決済後、新しい Pro キーがメールで送られます。再試行する前にそのキーを設定してください。現在の認証情報はそのままではアップグレードされません。

企業／ブランド

• crehq_companies_list — ブランドの一覧を取得し、カテゴリーや事業拡大状況で絞り込みます
• crehq_companies_search — ブランド名から CREHQ 企業 ID を特定します（ここから開始してください）
• crehq_company_get — 正規ブランドプロフィール、検証済み店舗数、所有者情報
• crehq_company_credit_signals — 信用プロフィール、スポンサー／発行体のコンテキスト、格付け、資本構成
• crehq_company_franchise — FDD の手数料、ロイヤリティ、投資額、Item 19 の数値
• crehq_company_real_estate — サイト選定基準と対象地域
• crehq_company_contacts — 不動産／開発の意思決定者の連絡先

立地情報

• crehq_locations_list — ブランド／州／カテゴリー別の店舗記録
• crehq_location_get — 全属性と検証履歴を含む、1件の立地情報
• crehq_locations_search — 複数の項目を対象としたあいまい検索
• crehq_locations_nearby — 緯度／経度を中心とした半径検索（商圏マッピング）
• crehq_locations_bulk — ID リスト、ブランドリスト、または GeoJSON ポリゴンによる一括取得
• crehq_locations_events — ブランド横断の開店／閉店／移転ライフサイクル情報
• crehq_location_history — 1店舗の完全なイベントログ

履歴と主要な差別化機能

• crehq_company_changes — 1ブランドの期間指定変更フィード
• crehq_company_occupancy — 特定時点の店舗一覧（過去の日付における店舗網）
• crehq_site_timeline — ある住所にこれまで入居したすべてのブランドの時系列 プレミアムインテリジェンス（Intel および Enterprise ティア）
• crehq_whitespace — 競合他社は出店しているものの、ブランドは出店していない市場
• crehq_co_tenancy — このブランドの店舗の近くに集まっているブランド
• crehq_location_site_profile — 1 か所の CREHQ モデル化サイトプロファイル
• crehq_company_site_pattern — 観測されたフットプリント／コンテキストに基づく、実証的なブランドの出店パターン
• crehq_recent_location_context — トラフィック、人口統計、カバレッジフラグを含む、最近観測された行／開店情報

モデル化サイトプロファイルの出力は、明示的に提示された要件の出典情報が 回答に含まれていない限り、企業が表明した出店要件ではなく、観測された 所在地／コンテキストデータに基づく CREHQ によるモデル化として記述する 必要があります。

モデル化サイトプロファイルの REST ルートは、明示的な本番環境での承認を 待って公開準備中です。これらのルートが公開されるまでは、MCP カタログで ローカルテスト用として案内されていても、これら 3 つのツールは 404 を 返す場合があります。

データセット

• crehq_datasets_list / crehq_dataset_get / crehq_dataset_download / crehq_dataset_categories
• crehq_purchased_datasets_list — 接続されたキーの所有者が購入したデータセットのスナップショットを、スナップショットの日付およびホスト型 MCP アクセスのステータスとともに一覧表示します。
• crehq_purchased_dataset_locations — ホスト型アクセス期間中に、購入者が所有する時点指定データセットのスナップショットから行を検索します。

トレンド

• crehq_trends_company — ブランドの店舗数／手数料／財務の時系列データ
• crehq_trends_geographic — 大都市圏／州ごとの集中度と成長速度

---

API キーの取得

1. 無料サンドボックス（月 1,000 回、2 req/s、クレジットカード不要。ブランドあたりの行数には月ごとの上限があり、各レスポンスに正確な行数の上限が表示されます）： https://crehq.com/developers/sandbox/ — メールアドレスを入力し、ブラウザーの認証チャレンジを完了すると、キーがメールで届きます。 キーはメールでのみ配布され、crehq_live_xxxxxxxx… のような形式です。 サンドボックスキーでは、上限付きの所在地検索（ブランドによる crehq_locations_list と、半径による crehq_locations_nearby）を実行でき、エンティティ関連付けリゾルバーを月に 1 回呼び出せます。ユーザーがプレミアムインテリジェンスを求めている場合は、crehq_request_upgrade を呼び出してください。これにより、CREHQ に対するフォローアップ依頼のトピックが記録され、ユーザーに必要なアップグレードが案内されます。
2. Pro MCP — 月額 99 ドル、セルフサービスの Stripe チェックアウト。上限付きの D1 所在地クエリ、選択された D2 出典情報フィールド、月 25,000 回のコア呼び出し、月最大 250 回の関連付けリゾルバー呼び出し、月 1 回の管理されたインテリジェンスプレビューが含まれます。https://crehq.com/developers/sandbox/#pro-checkout から開始してください。
3. データセット／インテリジェンス／Enterprise — ファイルが必要な場合は、ライセンス付きの時点指定データセットのスナップショットを購入してください。プレミアムインテリジェンス、更新プラン、API／フィード配信、再配布、組み込み利用権、SLA にはエンタープライズライセンスをご利用ください。https://crehq.com/pricing/ をご覧ください。

---

エージェントで CREHQ を最速で試す方法

1. https://crehq.com/developers/sandbox/ でサンドボックスキーを取得します。
2. ホスト型／リモート MCP クライアントでは、https://mcp.crehq.com/mcp を追加し、そのキーで認証します。
3. ローカル stdio クライアントでは、npx -y crehq-mcp-server でインストールし、CREHQ_API_KEY を設定します。
4. 次のように尋ねます：https://www.earleycrescent.org/ にある施設のブランド、運営者、親会社との関連性を CREHQ で特定してください。

セルフサービスキーでは、関連付けリゾルバー、上限付きの所在地検索、アップグレード案内、購入済みデータセットへのアクセス、管理されたインテリジェンスプレビューを利用できます。バックエンドでは引き続き、キーに適用される実際の Free、Pro、および購入済みデータセットの利用権限が適用され、必要に応じて、構造化されたアップグレードまたは購入のレスポンスが返されます。Intel および Enterprise キーでは、CREHQ のティアに応じて、より幅広い API ツールを利用できます。

---

インストールとビルド

Node.js ≥ 18 が必要です。

公開済みの stdio サーバーを npx でインストールします：

CREHQ_API_KEY=crehq_live_xxxxx npx crehq-mcp-server

または、ソースからビルドします：

git clone <this-repo> crehq-mcp-server
cd crehq-mcp-server
npm install
npm run build          # compiles TypeScript → dist/
cp .env.example .env    # then edit .env and set CREHQ_API_KEY

クライアントを接続する前に、ライブ API でキーを検証します：

export CREHQ_API_KEY=crehq_live_xxxxx
./test.sh               # exercises 6 read endpoints with curl

サーバーを単独で実行します（stdio 経由で MCP を使用するため、stdin でクライアントの接続を待ちます — 終了するには Ctrl-C を押します）：

CREHQ_API_KEY=crehq_live_xxxxx node dist/index.js

---

Claude Desktop に接続する

次の内容を claude_desktop_config.json に追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "crehq": {
      "command": "npx",
      "args": ["-y", "crehq-mcp-server"],
      "env": {
        "CREHQ_API_KEY": "crehq_live_your_key_here"
      }
    }
  }
}

Claude Desktop を再起動します。CREHQ ツールがツール（🔌）メニューに表示されます。

その他の MCP クライアント

stdio に対応する MCP クライアント（Claude Code、Cursor、Cline、Continue、 mcp CLI、カスタムの @modelcontextprotocol/sdk クライアントなど）は、同じ方法で接続できます。環境変数に CREHQ_API_KEY を設定し、サーバーコマンドとして node dist/index.js を実行します。

Claude Code：

claude mcp add crehq --env CREHQ_API_KEY=crehq_live_xxxxx -- npx crehq-mcp-server

ホスト型リモートコネクター

ホスト型 Cloudflare Worker 版は remote/ にあります。OAuth／キー交換と、プレミアムツール向けのスコープ制御を備えたリモート MCP サーバー https://mcp.crehq.com/mcp として、同じ CREHQ コネクターを提供します。デプロイに関するメモは remote/DEPLOY.md に、コネクターの提出用文面は remote/CONNECTOR-SUBMISSION.md にあります。

MCP Registry のメタデータは server.json にあり、レジストリの所有者は package.json の mcpName で宣言されています。

メンテナーのワークフロー

再現可能なリリース手順は GitHub Actions で管理されています。

• CI は、プッシュのたびに stdio パッケージとホスト型 Worker をビルドしてテストします。
• Deploy Remote MCP は remote/ の変更を Cloudflare Workers にデプロイし、その後 https://mcp.crehq.com/health を確認します。
• Publish npm は vX.Y.Z タグまたは手動のワークフロー実行により、stdio パッケージを公開します。パッケージの該当バージョンがすでに存在する場合は、安全にスキップします。

必要なリポジトリシークレットは、すでに次の名前で設定されています。

• NPM_TOKEN
• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

---

設定

環境変数	必須	デフォルト	用途
CREHQ_API_KEY	はい	—	お使いの crehq_live_… キー
CREHQ_API_BASE	いいえ	https://crehq.com/wp-json/crehq/v1	API のベース URLを上書きします（ステージング／プロキシ）
CREHQ_TIMEOUT_MS	いいえ	30000	リクエストごとのタイムアウト（ミリ秒）
CREHQ_API_SURFACE	いいえ	auto	サンドボックスキーとフルキーを自動検出します。デバッグ時は selfserve または full を指定できます

---

エラー処理

ツールの失敗によってエージェントのターンが中断されることはありません。エラーは、対処方法のヒントを添えた読みやすいメッセージとして返されます。

• キーが未設定 → CREHQ_API_KEY を設定するよう案内し、サンドボックスへのリンクを表示します。
• 401／403 → 「キーが無効または失効している／現在のプランではエンドポイントを利用できない」と表示し、アップグレード用リンクを示します。信用シグナル、FDD、サイト選定基準、連絡先、プロベナンス、変更履歴、一括データ、空きスペース、共同テナント、またはサイトのタイムラインについては、crehq_request_upgrade を呼び出してください。
• 404 → 「ID／スラッグを確認してください。まず検索ツールで解決してください」と表示します。
• 429 → Retry-After を尊重し、無料プランの上限が毎秒 2 リクエストであることを通知します。
• セルフサービスのガイダンス → API 自身の制限に関する情報を、そのまま渡します。API の message、row_budget（使用済み数／上限／基準／リセット）、full_dataset の案内、upgrade_url／enterprise_url、did_you_mean のスラッグ、およびブランドが展開されている市場が含まれます。セルフサービスの呼び出しが成功すると、JSON の行データの前に短いガイダンスブロック（coverage_note、total_available／has_more、row_budget、full_dataset、resolved_from、market_scope、Enhanced（D2）プレビューのラベル、フィールド、注記）が表示されます。
• 5xx／タイムアウト／ネットワークエラー → バックオフを設けて再試行するよう、一時的なエラーのガイダンスを表示します。

ページネーション、キャッシュ、ストリームのカーソル（X-WP-Total、X-CREHQ-Next-Since、X-CREHQ-Cache、レート制限ヘッダー）は、各結果の response metadata フッターに表示されるため、エージェントは適切にページネーションやポーリングを行えます。

---

テストに関する注意

ビルド、型チェック、MCP プロトコルのハンドシェイク、ツールカタログ、引数の検証、および HTTP リクエスト／レスポンス／エラー処理の全パイプラインは、本番 API に対してエンドツーエンドで検証されています（実際のリクエストでは、適切なヒントとともに 403 Invalid or revoked API key が返されます）。 実際のデータ行を取得するには有効なキーが必要です。サンドボックスキーはメールで送付されるため、CREHQ_API_KEY を設定して ./test.sh を実行し、実際のデータ応答を確認してください。

---

ライセンス

MIT。CREHQ のデータは、API のティア／契約に応じて別途ライセンスされています。