Local Falcon Mcp

Local Falcon MCP サーバー

Local Falcon の AI 可視性およびローカル検索インテリジェンスプラットフォーム向け MCP（Model Context Protocol）サーバー

---

AI 可視性およびローカル検索インテリジェンス MCP サーバー

Local Falcon は、AI 検索プラットフォーム、Google Maps、Apple Maps におけるビジネスの可視性を追跡する、AI 可視性およびローカル検索インテリジェンスプラットフォームです。この MCP サーバーは公式 MCP SDK を使用して TypeScript で実装されており、Local Falcon のスキャン、トラッキング、レポート作成、接続済みの Google Business Profile の管理機能を MCP クライアントに提供します。

---

特長

• スキャン、レポート作成、キャンペーン管理、競合分析、レビュー、Falcon Guard のモニタリング、Google Business Profile の管理に対応する MCP ツール
• インタラクティブな MCP Apps ウィジェット — Google Maps を使ったジオグリッドヒートマップ、色分けされた順位ピン、クリック可能な詳細パネル
• PKCE、リフレッシュトークンのサポート、動的クライアント登録を備えた OAuth 2.1
• 明示的なツールアノテーション — readOnlyHint、destructiveHint、openWorldHint によって、各ツールの作用と範囲を説明します
• マルチプラットフォーム対応 — Google Maps、Apple Maps、ChatGPT、Gemini、Google AI Overviews、AI Mode
• ChatGPT MCP コネクター互換 — OAuth スコープの整合、ウィジェットのサンドボックスドメイン、構造化コンテンツの解析
• ヒートマップウィジェットに表示される AI スクレイプコンテンツ向け HTML サニタイザー

---

前提条件

• Node.js（LTS バージョンをインストールしてください）

認証

OAuth（推奨）

Local Falcon MCP サーバーへの接続には、OAuth の利用を推奨します。安全なトークンベースの認証フローを提供するため、API キーを管理する必要はありません。Local Falcon にリダイレクトされてアクセスを許可すると、トークンは自動的に処理されます。

1. URL に https://mcp.localfalcon.com/mcp を設定します
2. 認証を OAuth に設定します
3. Client ID と Client Secret は空欄のままにします — クライアント登録はサーバーが自動的に処理します
4. Local Falcon にリダイレクトされたら、接続して認証します

Bearer トークン

MCP クライアントが OAuth に対応していない場合は、Local Falcon API キーを Bearer トークンとして使用できます。

1. URL に https://mcp.localfalcon.com/mcp を設定します
2. 認証を Bearer Token に設定します
3. Local Falcon API キーをトークン値として入力します

クエリ文字列による API キー

MCP クライアントが OAuth または Bearer トークン認証に対応していない場合は、API キーを URL に直接渡すことができます。

https://mcp.localfalcon.com/mcp?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE

---

リモート（HTTP）での実行

mcp-remote を使用する MCP クライアント向け（すべてのプラットフォーム）：

{
  "mcpServers": {
    "local-falcon-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.localfalcon.com/mcp?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE"
      ]
    }
  }
}

リモート（SSE — レガシー）での実行

/sse エンドポイントはレガシーと見なされており、今後のバージョンで削除される予定です。代わりに /mcp エンドポイントを使用してください。

{
  "mcpServers": {
    "local-falcon-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.localfalcon.com/sse?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE"
      ]
    }
  }
}

STDIO 経由での実行

ワンクリックでインストール： 最新の .mcpb バンドルを Releases からダウンロードし、Claude Desktop で開きます。手動でインストールする場合は、以下の手順に従ってください。

ローカルにインストールする場合は、まずパッケージをインストールします。

mkdir lf-mcp
cd lf-mcp
npm i @local-falcon/mcp

MacOS/Unix の場合：

{
  "mcpServers": {
    "local-falcon-mcp": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/lf-mcp/node_modules/@local-falcon/mcp/dist/index.js"],
      "env": {
        "LOCAL_FALCON_API_KEY": "INSERT_YOUR_API_KEY_HERE"
      }
    }
  }
}

Windows の場合：

{
  "mcpServers": {
    "local-falcon-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\lf-mcp\\node_modules\\@local-falcon\\mcp\\dist\\index.js"],
      "env": {
        "LOCAL_FALCON_API_KEY": "INSERT_YOUR_API_KEY_HERE"
      }
    }
  }
}

---

MCP Apps

このサーバーには、対応する AI クライアント（Claude、ChatGPT）内で表示されるインタラクティブな MCP Apps ウィジェットが含まれています。

地域グリッドヒートマップ

getLocalFalconReport を呼び出すと、MCP Apps に対応したクライアントに、次の機能を備えたインタラクティブな地域グリッドヒートマップウィジェットが表示されます。

• 指標バー — キーワード、ビジネス名、グリッドサイズ、ARP、ATRP、SoLV、スキャン日
• Google Maps — 色分けされた順位ピン（緑＝順位 1、赤＝順位 9 以上）を備えた、完全にインタラクティブな地図
• 詳細パネル — 任意のピンをクリックすると、そのグリッド地点にあるビジネスの詳細情報（評価、レビュー、カテゴリ、AI スクレイピングコンテンツを含む）が表示されます
• HTML サニタイザー — AI スクレイピングコンテンツは、安全なタグ、属性、画像ドメインの許可リストに基づいてサニタイズされてから表示されます

このウィジェットは、Vite を使用した単一ファイルの HTML アプリケーションとして構築され、MCP App リソースとして提供されます。

---

デプロイプロファイル

同じ https://mcp.localfalcon.com/mcp エンドポイントが、ChatGPT として識別された認証済みセッションには57 個のツールを、その他の MCP クライアントには60 個のツールを自動的に公開します。プロファイルの選択には、requestSource.ts にある既存のリクエスト元の識別機能を再利用します。別のエンドポイント、デプロイプロファイル用変数、追加のクライアント検出機能はありません。プロファイルは認証済みセッションに紐付けられ、ChatGPT と判定された API 呼び出しでは、後続の処理でも request_source=chatgpt が保持されます。

セッションプロファイルは、認証と所有権の確認後に紐付けられます。確立済みの ChatGPT セッションでは、後からのシグナルが欠落している場合や、より弱い場合でも、その識別情報が保持されます。通常プロファイルから ChatGPT プロファイルへの変更が後から発生した場合は、以降のツール実行前に新たな初期化が必要です。プロファイルは、認証情報に紐付けられたレコードがメモリ内にある間（最大 24 時間、容量上限あり）は復旧時にも保持されます。プロセスの再起動後、またはレコードの期限切れや削除後は、クライアントは再初期化する必要があります。レガシー SSE は、ツールを登録する前に初期化を待機します。

ChatGPT プロファイルでは、getLocalFalconGoogleBusinessLocations、getLocalFalconRankingAtCoordinate、getLocalFalconKeywordAtCoordinate は登録されません。これらのオンデマンドツールは、別途課金される利用状況を記録するためです。通常プロファイルとオンデマンド API では、これらの機能を引き続き利用できます。getLocalFalconGrid は両方のプロファイルで引き続き利用できます。また、searchForLocalFalconBusinessLocation も利用でき、検索が成功するたびに既存クレジットを正確に2 クレジット消費します。

ChatGPT プロファイルは既存アカウント向けの連携機能です。既存アカウントの利用資格やクレジットは使用できますが、クレジットの購入、自動チャージの実行、チェックアウトの開始、サブスクリプションの変更、アップグレードの案内、または別途の金銭的な利用料金の発生は禁止されています。プランと利用資格への中立的な情報リンクは許可されています。ChatGPT への応答では、Local Falcon のエラーを正規化し、取引に関するアカウント文言やリンクを削除するとともに、ナレッジベースの記事 ID 15、16、23、37、57、81 を検索および直接取得の対象から除外します。通常プロファイルのナレッジベースへのアクセスに変更はありません。記事 28、50、58 は引き続き利用できます。

ChatGPT のデプロイチェックリスト

1. レビュー済みの MCP コードを既存のサービスにデプロイし、ChatGPT やその他のクライアントで同じ /mcp URL を使用します。
2. ChatGPT によるセッションとその他のクライアントのセッションを使い、期待されるプロファイルに対して認証済みの tools/list を検証します。ChatGPT のセッションから除外された 3 つのツールを直接呼び出せないことを確認します。
3. 提出の必須条件： 最終的な OpenAI への提出前に、Pia は残りのスケジュール済みキャンペーンに対する自動リチャージ防止策を LF.api/LF.internal にデプロイして検証する必要があります。MCP のレスポンスフィルタリングとプロファイル選択だけでは、バックエンドでの課金分離が証明されたことにはなりません。
4. Shaun/Pia は、別途実施する LF.app OAuth の権限表示文言の変更をレビューしてデプロイする必要があります。この変更は MCP サービスとともにはデプロイされません。

これらはデプロイ手順であり、本番環境での変更を記録したものではありません。実装作業では、本番インフラを変更したり、いずれかのアプリケーションをデプロイしたりすることはありません。

ツール

すべてのツールで、3 つの MCP アノテーションヒントを明示的に宣言しています。ヒントは動作を説明するものであり、認可や重大な操作に対する確認の代わりにはなりません。

アノテーション	このサーバーでの意味
readOnlyHint: true	状態を変更したり、クレジットや従量課金の利用量を消費したりせずにデータを取得します。
destructiveHint: true	クレジットを消費する、今後のクレジット利用を有効にする、または既存の状態を上書き・削除します。元に戻せることだけを理由に、更新が非破壊的になるわけではありません。
openWorldHint: false	範囲が限定されたアカウントデータ、接続済みの GBP の読み取り、固定された Local Falcon KB、またはローカルでのグリッド計算を扱います。データの過去の取得元は、このヒントの判定には影響しません。
openWorldHint: true	オープンな公開システムを検索する、公開スキャンをスケジュールまたは実行する、または公開 GBP を公開・編集します。

スキャンレポート

• listLocalFalconScanReports：既存のスキャンレポートをすべて一覧表示します。重複を避けるため、新しいスキャンを実行する前にまずここを確認してください。
• getLocalFalconReport：レポートキー（例：https://www.localfalcon.com/reports/view/XXXXX）で特定のスキャンレポートを取得します。MCP Apps 対応クライアントでは、操作可能なジオグリッドヒートマップを表示します。
• runLocalFalconScan：指定された座標で新しいスキャンを実行し、ビジネスのランキングデータを取得します。

キャンペーン管理

• listLocalFalconCampaignReports：すべてのキャンペーンレポートを一覧表示します。キャンペーンでは、スケジュールに沿ったスキャンを通じて、大規模にランキングを追跡します。
• getLocalFalconCampaignReport：特定のキャンペーンレポートを取得します（例：https://www.localfalcon.com/campaigns/view/XXXXX）。
• createLocalFalconCampaign：定期的なスキャンをスケジュールした新しいキャンペーンを作成します。
• updateLocalFalconCampaign：既存のキャンペーンの設定、場所、キーワードを編集します。
• runLocalFalconCampaign：キャンペーンを手動で直ちに実行します。
• pauseLocalFalconCampaign：キャンペーンのスケジュール実行を一時停止します。
• resumeLocalFalconCampaign：一時停止中のキャンペーンを再開します。
• reactivateLocalFalconCampaign：クレジット不足により無効化されたキャンペーンを再有効化します。

クチコミ分析

• listLocalFalconReviewsAnalysisReports：AI によるクチコミ分析情報を含む、すべてのクチコミ分析レポートを一覧表示します。
• getLocalFalconReviewsAnalysisReport：特定のクチコミ分析レポートを取得します。

Falcon Guard（GBP モニタリング）

• listLocalFalconGuardReports：モニタリング対象の場所に関する Falcon Guard レポートを一覧表示します。
• getLocalFalconGuardReport：place_id で特定の Falcon Guard レポートを取得します。
• addLocationsToFalconGuard：Falcon Guard の保護対象に場所を追加します。
• pauseFalconGuardProtection：指定した場所の保護を一時停止します。
• resumeFalconGuardProtection：一時停止中の場所の保護を再開します。
• removeFalconGuardProtection：Falcon Guard から場所を完全に削除します。

トレンドレポート

• listLocalFalconTrendReports：時間の経過に伴うランキングの変化を示す、自動生成されたトレンドレポートを一覧表示します。
• getLocalFalconTrendReport：特定のトレンドレポートを取得します（例：https://www.localfalcon.com/reports/trend/view/XXXXX）。

自動スキャン

• listLocalFalconAutoScans：キャンペーンベースではない、個別にスケジュールされた自動スキャンを一覧表示します。

ロケーションレポート

• listLocalFalconLocationReports：特定のロケーションのスキャンを集約した自動生成レポートを一覧表示します。
• getLocalFalconLocationReport：特定のロケーションレポートを取得します（例：https://www.localfalcon.com/reports/location/view/XXXXX）。

キーワードレポート

• listLocalFalconKeywordReports：特定のキーワードのスキャンを集約した自動生成レポートを一覧表示します。
• getLocalFalconKeywordReport：特定のキーワードレポートを取得します（例：https://www.localfalcon.com/reports/keyword/view/XXXXX）。

競合他社レポート

• getLocalFalconCompetitorReports：自動生成された競合分析レポートを一覧表示します。
• getLocalFalconCompetitorReport：特定の競合他社レポートを取得します（例：https://www.localfalcon.com/reports/competitor/view/XXXXX）。

ロケーション管理

• listAllLocalFalconLocations：アカウントに保存されているすべてのビジネスロケーションを一覧表示します。
• listLocalFalconLocationGroups：アカウントに保存されているロケーショングループを一覧表示します。
• getLocalFalconGoogleBusinessLocations：Googleでビジネスリスティングを検索し、Place IDを見つけます。
• searchForLocalFalconBusinessLocation：GoogleまたはAppleのプラットフォームでビジネスロケーションを検索します。検索が成功するごとに、既存のLocal Falconクレジットを2消費します。
• saveLocalFalconBusinessLocationToAccount：ビジネスロケーションをアカウントに保存します。

オンデマンドツール

• getLocalFalconGrid：単一点チェック用のグリッド座標を生成するヘルパーツールです。
• getLocalFalconRankingAtCoordinate：1つの座標で単一点のランキングを確認します。
• getLocalFalconKeywordAtCoordinate：1つの座標で単一点のキーワード検索を行います。

ナレッジベース

• searchLocalFalconKnowledgeBase：Local Falconナレッジベースを検索し、ヘルプ記事、操作ガイド、プラットフォームのドキュメントを探します。
• getLocalFalconKnowledgeBaseArticle：IDを指定して、特定のナレッジベース記事の全文を取得します。

アカウント

• viewLocalFalconAccountInformation：ユーザー、クレジット、サブスクリプションの詳細など、アカウント情報を取得します。

---

Google ビジネスプロフィールを管理する

所在地に紐づくライブの Google ビジネスプロフィールに対して操作します。Local Falcon のレポートデータに対する操作ではありません。すべての操作で、Local Falcon ダッシュボード上でその所在地が Google アカウントに接続されている必要があります。

• getLocalFalconGbpProfile：ライブのプロフィールを取得します。名前、住所、電話番号、カテゴリ、営業時間、ウェブサイト、営業状況が含まれます。
• getLocalFalconGbpGoogleUpdates：Google が保留しているプロフィールのバージョンを取得し、未適用の Google 提案による編集を見つけます。
• getLocalFalconGbpVerificationStatus：Google の確認状況を調べます。未確認または停止中のプロフィールは、ランキングが低いか、まったく表示されません。
• getLocalFalconGbpAttributes：現在プロフィールに設定されている属性を一覧表示します。
• getLocalFalconGbpAvailableAttributes：カテゴリに対して Google が許可している属性と、想定される値の型を一覧表示します。
• listLocalFalconGbpServices：プロフィールに登録されているサービスを、説明と価格とともに一覧表示します。
• getLocalFalconGbpPerformanceMetrics：Google 独自のエンゲージメント指標（インプレッション、通話、ウェブサイトのクリック、ルート検索リクエスト）を取得します。
• listLocalFalconGbpPosts：プロフィールの投稿（最新情報、イベント、オファー、お知らせ）を一覧表示します。
• listLocalFalconGbpMedia：オーナーがアップロードした写真や動画を、カテゴリで絞り込んで一覧表示します。
• listLocalFalconGbpCustomerMedia：顧客がアップロードした写真や動画を一覧表示します。
• listLocalFalconGbpReviews：Google のクチコミとオーナーの返信を一覧表示します。評価または未返信で絞り込めます。
• listLocalFalconGbpActionLinks：アクションリンク（予約、注文、アポイントメント）を一覧表示します。
• getLocalFalconGbpAvailableActionTypes：プロフィールが対応するアクションリンクの種類を一覧表示します。
• searchLocalFalconGbpCategories：Google のカテゴリ分類を検索して、gcid: 識別子を取得します。
• searchLocalFalconGbpChains：Google のチェーンディレクトリを検索します。
• manageLocalFalconGbpPosts：投稿を作成、更新、削除します。Google に直接反映されます。
• manageLocalFalconGbpMedia：オーナーのメディアを追加、再分類、削除します。Google に直接反映されます。
• manageLocalFalconGbpReviewReplies：クチコミへの公開返信を、個別または一度に最大 50 件まで投稿または削除します。
• manageLocalFalconGbpActionLinks：アクションリンクを追加、更新、削除します。
• manageLocalFalconGbpServices：サービスを追加、削除、または一括置換します。replace はリスト全体を上書きします。
• updateLocalFalconGbpProfile：基本情報、営業時間、営業状況、属性を更新します。CLOSED_PERMANENTLY は実質的に取り消せません。

スキル

このリポジトリには、skills/ 配下に 2 つの AI スキルが含まれています。

スキル	パス	説明
Local Falcon MCP	skills/local-falcon-mcp/	ChatGPT プロフィール向けの MCP ツール使用ガイダンス
Local Visibility	skills/local-visibility-skill/	AI による可視性とローカル SEO の一般的な戦略 — プラットフォーム分析、指標の解釈、プロンプトテンプレート

---

開発者向け

注： エンドユーザーがこのサーバーをインストールして実行するには、Node.js（LTS）と npm のみが必要です。以下の手順は、ソースコードを扱うコントリビューターと開発者向けです。

前提条件

• Node.js 18 以降（LTS を推奨）
• npm（Node.js に同梱）

ビルド

npm install
npm run build

ビルドでは、TypeScript を dist/ にコンパイルし、MCP Apps UI ウィジェットを dist/ui/ にビルドします。

MCP Inspector を実行

npm run inspector

MCP サーバーを実行

npm run start             # STDIO mode (default)
npm run start:sse         # SSE mode with OAuth
npm run start:http        # HTTP mode with OAuth
npm run start:HTTPAndSSE  # Both SSE and HTTP

---

ライセンス

MIT

---

謝辞

• Local Falcon API ドキュメント
• Model Context Protocol（MCP）
• @modelcontextprotocol/sdk（Anthropic MCP SDK）
• @modelcontextprotocol/ext-apps（MCP Apps SDK）