Local Falcon Mcp

Local Falcon MCP 服务

用于 Local Falcon AI 可见度和本地搜索智能平台的 MCP（Model Context Protocol）服务

---

AI 可见度和本地搜索智能 MCP 服务

Local Falcon 是一个 AI 可见度和本地搜索智能平台，可跟踪商家在 AI 搜索平台、Google Maps 和 Apple Maps 上的可见度。此 MCP 服务使用官方 MCP SDK 以 TypeScript 实现，并向 MCP 客户端提供 Local Falcon 扫描、跟踪、报告以及已连接的 Google Business Profile 管理功能。

---

功能

• MCP 工具，用于扫描、报告、活动管理、竞争对手分析、评价、Falcon Guard 监控和 Google Business Profile 管理
• 交互式 MCP Apps 小组件 — 带有 Google Maps、彩色排名图钉和可点击详情面板的地理网格热力图
• OAuth 2.1，支持 PKCE、刷新令牌和动态客户端注册
• 明确的工具注释 — readOnlyHint、destructiveHint 和 openWorldHint 描述每个工具的影响和范围
• 多平台支持 — Google Maps、Apple Maps、ChatGPT、Gemini、Google AI Overviews、AI Mode
• 兼容 ChatGPT MCP connector — OAuth 作用域对齐、小组件沙盒域名、结构化内容解析
• HTML 清理器，用于处理热力图小组件中显示的 AI 抓取内容

---

前提条件

• Node.js（安装 LTS 版本）

身份验证

OAuth（推荐）

OAuth 是连接 Local Falcon MCP 服务的推荐方式。它提供安全的基于令牌的身份验证流程，无需管理 API 密钥。系统会将你重定向到 Local Falcon 以授权访问，并自动处理令牌。

1. 将 URL 设置为 https://mcp.localfalcon.com/mcp
2. 将 Authentication 设置为 OAuth
3. 将 Client ID 和 Client Secret 留空 — 服务会自动处理客户端注册
4. 连接，并在重定向到 Local Falcon 后进行授权

Bearer Token

如果你的 MCP 客户端不支持 OAuth，可以使用 Local Falcon API 密钥作为 Bearer 令牌。

1. 将 URL 设置为 https://mcp.localfalcon.com/mcp
2. 将 Authentication 设置为 Bearer Token
3. 将 Local Falcon API 密钥填入令牌值

通过查询字符串传递 API 密钥

如果你的 MCP 客户端不支持 OAuth 或 Bearer Token 身份验证，可以直接在 URL 中传递 API 密钥：

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 运行

一键安装： 从 Releases 下载最新的 .mcpb 软件包，并在 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

该服务包含一个交互式 MCP Apps 小组件，可在支持的 AI 客户端（Claude、ChatGPT）中显示。

地理网格热力图

调用 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. 提交门槛： Pia 必须在最终提交给 OpenAI 之前，在 LF.api/LF.internal 中部署并验证剩余的定时营销活动无自动充值保护。MCP 响应筛选和配置文件选择本身并不能证明后端费用已隔离。
4. Shaun/Pia 必须审核并部署独立的 LF.app OAuth 权限措辞变更。这些变更不会随 MCP 服务一起部署。

这些是部署说明，并非生产环境变更记录。实施工作不会更改生产基础设施，也不会部署任一应用程序。

工具

所有工具都明确声明了三个 MCP 注解提示。提示描述行为；不能替代授权或对重大操作的确认。

注解	此服务中的含义
readOnlyHint: true	获取数据，不更改状态，也不消耗积分或计费额度。
destructiveHint: true	消耗积分、启用未来的积分使用，或覆盖/移除现有状态。仅仅可逆并不意味着更新就不是破坏性操作。
openWorldHint: false	与范围受限的账户数据、已连接的 GBP 读取、固定的 Local Falcon 知识库或本地网格计算交互。数据的历史来源不会决定此提示。
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 平台上搜索营业地点。每次成功搜索会消耗 2 个现有 Local Falcon 点数。
• saveLocalFalconBusinessLocationToAccount：将营业地点保存到账户中。

按需工具

• getLocalFalconGrid：用于生成单点检查网格坐标的辅助工具。
• getLocalFalconRankingAtCoordinate：在一个坐标处进行单点排名检查。
• getLocalFalconKeywordAtCoordinate：在一个坐标处进行单点关键词搜索。

知识库

• searchLocalFalconKnowledgeBase：在 Local Falcon 知识库中搜索帮助文章、操作指南和平台文档。
• getLocalFalconKnowledgeBaseArticle：通过 ID 获取特定知识库文章的完整内容。

账户

• viewLocalFalconAccountInformation：获取账户信息，包括用户、点数和订阅详情。

---

管理 Google Business Profile

对某个地点关联的实时 Google Business Profile 执行操作，而非 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/ 下包含两项 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）