Local Falcon MCP Server
Local Falcon MCP server exposes Local Falcon local search and AI visibility data plus account management capabilities to MCP clients.
List and retrieve scan, trend, location, keyword, competitor, campaign, auto-scan, and Falcon Guard reports.
Run and manage scans, including full-grid searches and single-coordinate ranking/keyword checks.
Generate grid coordinates for local ranking checks.
Search, list, and save business locations, including Google/Apple business search and Place ID lookup.
Create, update, run, pause, resume, and reactivate scheduled campaigns.
Manage Falcon Guard monitoring by adding, pausing, resuming, or removing locations.
Access account information and search Local Falcon Knowledge Base articles.
Read and manage connected Google Business Profiles, including posts, media, reviews, services, action links, attributes, hours, and profile details.
Provides tools for retrieving Google Business location data, analyzing search rankings at specific coordinates, and performing grid searches for business rankings across geographic areas.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Local Falcon MCP Server show me recent scan reports for my coffee shop locations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local Falcon MCP Server
AI Visibility and Local Search Intelligence MCP Server
Local Falcon is an AI visibility and local search intelligence platform that tracks business visibility across AI search platforms, Google Maps, and Apple Maps. This MCP server is implemented in TypeScript using the official MCP SDK and exposes Local Falcon scanning, tracking, reporting, and connected Google Business Profile management to MCP clients.
Related MCP server: AgentSEO MCP Server
Features
MCP tools for scanning, reporting, campaign management, competitor analysis, reviews, Falcon Guard monitoring, and Google Business Profile management
Interactive MCP Apps widget — geo-grid heatmap with Google Maps, colored rank pins, and clickable detail panels
OAuth 2.1 with PKCE, refresh token support, and dynamic client registration
Explicit tool annotations —
readOnlyHint,destructiveHint, andopenWorldHintdescribe each tool's effects and scopeMulti-platform — Google Maps, Apple Maps, ChatGPT, Gemini, Google AI Overviews, AI Mode
ChatGPT MCP connector compatible — OAuth scope alignment, widget sandbox domain, structured content parsing
HTML sanitizer for AI scrape content displayed in the heatmap widget
Prerequisites
Node.js (install the LTS version)
Authentication
OAuth (Recommended)
OAuth is the recommended way to connect to the Local Falcon MCP server. It provides a secure, token-based authentication flow — no API key management required. You'll be redirected to Local Falcon to authorize access, and tokens are handled automatically.
Set the URL to
https://mcp.localfalcon.comSet Authentication to OAuth
Leave Client ID and Client Secret empty — the server handles client registration automatically
Connect and authorize when redirected to Local Falcon
Bearer Token
If your MCP client does not support OAuth, you can use your Local Falcon API key as a Bearer token.
Set the URL to
https://mcp.localfalcon.comSet Authentication to Bearer Token
Enter your Local Falcon API key as the token value
API Key via Query String
If your MCP client does not support OAuth or Bearer Token authentication, you can pass your API key directly in the URL:
https://mcp.localfalcon.com/?local_falcon_api_key=INSERT_YOUR_API_KEY_HERERunning via Remote (HTTP)
For MCP clients that use mcp-remote (all platforms):
{
"mcpServers": {
"local-falcon-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.localfalcon.com/?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE"
]
}
}
}Running via Remote (SSE — Legacy)
The /sse endpoint is considered legacy and will be removed in a future version. Use https://mcp.localfalcon.com (Streamable HTTP) instead.
{
"mcpServers": {
"local-falcon-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.localfalcon.com/sse?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE"
]
}
}
}Running via STDIO
One-click install: Download the latest .mcpb bundle from Releases and open it in Claude Desktop. For manual installation, follow the steps below.
For local installations, first install the package:
mkdir lf-mcp
cd lf-mcp
npm i @local-falcon/mcpFor 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"
}
}
}
}For 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
The server includes an interactive MCP Apps widget that renders inside supported AI clients (Claude, ChatGPT).
Geo-Grid Heatmap
When you call getLocalFalconReport, clients that support MCP Apps will display an interactive geo-grid heatmap widget featuring:
Metrics bar — keyword, business name, grid size, ARP, ATRP, SoLV, scan date
Google Maps — full interactive map with colored rank pins (green = rank 1, red = rank 9+)
Detail panel — click any pin to see the full business listing at that grid point with ratings, reviews, categories, and AI scrape content
HTML sanitizer — AI scrape content is sanitized with an allowlist of safe tags, attributes, and image domains before rendering
The widget is built as a single-file HTML application using Vite and served as an MCP App resource.
Deployment profiles
The same https://mcp.localfalcon.com endpoint automatically exposes 57 tools to authenticated sessions identified as ChatGPT and 60 tools to other MCP clients. Profile selection reuses the existing request-source attribution in requestSource.ts; there is no separate endpoint, deployment profile variable, or additional client detector. The profile is bound to the authenticated session, and recognized ChatGPT API calls retain request_source=chatgpt downstream.
Session profiles are bound after authentication and ownership checks. Established ChatGPT sessions retain their attribution when later signals are missing or weaker. A later normal-to-ChatGPT change requires a fresh initialization before more tools can run. Recovery retains the profile while its credential-bound record remains in memory (up to 24 hours, bounded by capacity); after a process restart or record expiry/eviction, clients must initialize again. Legacy SSE waits for initialization before registering its tools.
The ChatGPT profile does not register getLocalFalconGoogleBusinessLocations, getLocalFalconRankingAtCoordinate, or getLocalFalconKeywordAtCoordinate, because these On-Demand tools record separately billable usage. The normal profile and On-Demand API retain those capabilities. getLocalFalconGrid remains available in both profiles, as does searchForLocalFalconBusinessLocation, which costs exactly 2 existing credits per successful search.
The ChatGPT profile is an existing-account integration. It may use existing account entitlements and credits, but must not buy credits, trigger Auto Recharge, initiate checkout, change subscriptions, promote upgrades, or cause separate monetary usage charges. A neutral informational link to plans and entitlements is allowed. ChatGPT responses normalize Local Falcon failures, remove transactional account copy/links, and exclude Knowledge Base article IDs 15, 16, 23, 37, 57, and 81 from search and direct retrieval. Normal-profile KB access is unchanged; articles 28, 50, and 58 remain available.
ChatGPT deployment checklist
Deploy the reviewed MCP code to the existing service and use the same
https://mcp.localfalcon.comURL for ChatGPT and other clients.Verify authenticated
tools/listwith ChatGPT-attributed and other-client sessions against the expected profiles. Confirm that the three excluded tools cannot be called directly from ChatGPT sessions.Submission gate: Pia must deploy and verify the remaining scheduled-campaign no-Auto-Recharge protection in LF.api/LF.internal before final OpenAI submission. MCP response filtering and profile selection do not themselves prove backend charge isolation.
Shaun/Pia must review and deploy the separate LF.app OAuth entitlement wording changes. They are not deployed with the MCP service.
These are deployment instructions, not a record of production changes. The implementation work does not change production infrastructure or deploy either application.
Tools
All tools explicitly declare the three MCP annotation hints. Hints describe behavior; they are not a substitute for authorization or confirmation of consequential actions.
Annotation | Meaning in this server |
| Retrieves data without changing state or consuming credits/billable usage. |
| Spends credits, enables future credit use, or overwrites/removes existing state. Reversibility alone does not make an update non-destructive. |
| Interacts with bounded account data, connected GBP reads, the fixed Local Falcon KB, or local grid arithmetic. Data's historical origin does not determine this hint. |
| Searches open public systems, schedules/runs public scans, or publishes/edits a public GBP. |
Scan Reports
listLocalFalconScanReports: Lists all existing scan reports. Check here first before running new scans to avoid duplicates.
getLocalFalconReport: Retrieves a specific scan report by report key (e.g.,
https://www.localfalcon.com/reports/view/XXXXX). Renders an interactive geo-grid heatmap in MCP Apps-capable clients.runLocalFalconScan: Runs a new scan at the specified coordinates to get ranking data for a business.
Campaign Management
listLocalFalconCampaignReports: Lists all campaign reports. Campaigns track rankings at scale with scheduled scans.
getLocalFalconCampaignReport: Retrieves a specific campaign report (e.g.,
https://www.localfalcon.com/campaigns/view/XXXXX).createLocalFalconCampaign: Creates a new campaign with scheduled recurring scans. Optionally sets the platforms, the keyword type (maps, AI or both) and per-location grids or platforms.
updateLocalFalconCampaign: Edits an existing campaign — settings, locations or keywords.
runLocalFalconCampaign: Manually triggers a campaign to run immediately.
pauseLocalFalconCampaign: Pauses a campaign's scheduled runs.
resumeLocalFalconCampaign: Resumes a paused campaign.
reactivateLocalFalconCampaign: Reactivates a campaign deactivated due to insufficient credits.
Reviews Analysis
listLocalFalconReviewsAnalysisReports: Lists all Reviews Analysis reports with AI-powered review insights.
getLocalFalconReviewsAnalysisReport: Retrieves a specific Reviews Analysis report.
Falcon Guard (GBP Monitoring)
listLocalFalconGuardReports: Lists Falcon Guard reports for monitored locations.
getLocalFalconGuardReport: Retrieves a specific Falcon Guard report by place_id.
addLocationsToFalconGuard: Adds locations to Falcon Guard protection.
pauseFalconGuardProtection: Pauses protection for specified locations.
resumeFalconGuardProtection: Resumes protection for paused locations.
removeFalconGuardProtection: Removes locations from Falcon Guard entirely.
Trend Reports
listLocalFalconTrendReports: Lists auto-generated trend reports showing ranking changes over time.
getLocalFalconTrendReport: Retrieves a specific trend report (e.g.,
https://www.localfalcon.com/reports/trend/view/XXXXX).
Auto Scans
listLocalFalconAutoScans: Lists individually scheduled automatic scans (not campaign-based).
Location Reports
listLocalFalconLocationReports: Lists auto-generated reports aggregating scans for specific locations.
getLocalFalconLocationReport: Retrieves a specific location report (e.g.,
https://www.localfalcon.com/reports/location/view/XXXXX).
Keyword Reports
listLocalFalconKeywordReports: Lists auto-generated reports aggregating scans for specific keywords.
getLocalFalconKeywordReport: Retrieves a specific keyword report (e.g.,
https://www.localfalcon.com/reports/keyword/view/XXXXX).
Competitor Reports
getLocalFalconCompetitorReports: Lists auto-generated competitor analysis reports.
getLocalFalconCompetitorReport: Retrieves a specific competitor report (e.g.,
https://www.localfalcon.com/reports/competitor/view/XXXXX).
Location Management
listAllLocalFalconLocations: Lists all business locations saved in your account.
listLocalFalconLocationGroups: Lists saved location groups in the account.
getLocalFalconGoogleBusinessLocations: Searches Google for business listings to find Place IDs.
searchForLocalFalconBusinessLocation: Searches for business locations on Google or Apple platforms. Costs 2 existing Local Falcon credits per successful search.
saveLocalFalconBusinessLocationToAccount: Saves a business location to your account.
On-Demand Tools
getLocalFalconGrid: Helper tool that generates grid coordinates for single-point checks.
getLocalFalconRankingAtCoordinate: Single-point ranking check at one coordinate.
getLocalFalconKeywordAtCoordinate: Single-point keyword search at one coordinate.
Knowledge Base
searchLocalFalconKnowledgeBase: Searches the Local Falcon Knowledge Base for help articles, how-to guides, and platform documentation.
getLocalFalconKnowledgeBaseArticle: Retrieves the full content of a specific Knowledge Base article by ID.
Account
viewLocalFalconAccountInformation: Retrieves account info including user, credits, and subscription details.
Manage Google Business Profile
Act on the live Google Business Profile behind a location, not on Local Falcon report data. All require the location to be connected to a Google account in your Local Falcon dashboard.
getLocalFalconGbpProfile: Retrieves the live profile — name, address, phone, categories, hours, website, open status.
getLocalFalconGbpGoogleUpdates: Retrieves Google's pending version of the profile, for spotting unapplied Google-suggested edits.
getLocalFalconGbpVerificationStatus: Checks Google verification state. Unverified or suspended profiles rank poorly or not at all.
getLocalFalconGbpAttributes: Lists attributes currently set on the profile.
getLocalFalconGbpAvailableAttributes: Lists attributes Google permits for a category, with expected value types.
listLocalFalconGbpServices: Lists services on the profile, with descriptions and prices.
getLocalFalconGbpPerformanceMetrics: Google's own engagement metrics — impressions, calls, website clicks, direction requests.
listLocalFalconGbpPosts: Lists profile posts (updates, events, offers, alerts).
listLocalFalconGbpMedia: Lists owner-uploaded photos and videos, filterable by category.
listLocalFalconGbpCustomerMedia: Lists customer-uploaded photos and videos.
listLocalFalconGbpReviews: Lists Google reviews and owner replies. Filter by rating or unanswered.
listLocalFalconGbpActionLinks: Lists action links (booking, ordering, appointments).
getLocalFalconGbpAvailableActionTypes: Lists action link types the profile supports.
searchLocalFalconGbpCategories: Searches Google's category taxonomy for
gcid:identifiers.searchLocalFalconGbpChains: Searches Google's chain directory.
manageLocalFalconGbpPosts: Creates, updates or deletes a post. Writes live to Google.
manageLocalFalconGbpMedia: Adds, recategorises or deletes owner media. Writes live to Google.
manageLocalFalconGbpReviewReplies: Publishes or deletes public replies to reviews, singly or up to 50 at once.
manageLocalFalconGbpActionLinks: Adds, updates or removes action links.
manageLocalFalconGbpServices: Adds, removes or wholesale-replaces services.
replaceoverwrites the entire list.updateLocalFalconGbpProfile: Updates core details, hours, open status or attributes.
CLOSED_PERMANENTLYis effectively irreversible.
Destructive GBP actions require the user's approval
Deleting a post, media item, review reply or action link, wholesale-replacing services, setting attributes, and marking a profile CLOSED_PERMANENTLY are gated by the server before anything is sent to Google. In clients that support MCP elicitation, the server shows the user an approval dialog and proceeds only on an explicit accept. If the dialog is not answered within a few seconds, or cannot be delivered, the tool falls back to the token flow described next, and an unanswered dialog is never treated as approval. In other clients the tool first returns a confirmation_required preview describing the exact operation, with a single-use confirmationToken that expires after 10 minutes; the AI must show that preview to the user and call the tool again with identical arguments plus the token only after the user approves. A token issued for different arguments, already used, or expired is refused. The API's own literal confirmation tokens are still supplied by the server once approval is obtained.
Skills
This repo includes two AI skills under skills/:
Skill | Path | Description |
Local Falcon MCP |
| MCP tool usage guidance for the ChatGPT profile |
Local Visibility |
| General AI visibility & local SEO strategy — platform analysis, metrics interpretation, prompt templates |
For Developers
Note: End users only need Node.js (LTS) and npm to install and run this server. The instructions below are for contributors and developers working on the source code.
Prerequisites
Node.js 18+ (LTS recommended)
npm (included with Node.js)
Build
npm install
npm run buildThe build compiles TypeScript to dist/ and builds the MCP Apps UI widget to dist/ui/.
Run MCP Inspector
npm run inspectorRun MCP Server
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 HTTPLicense
MIT
Acknowledgments
@modelcontextprotocol/sdk (Anthropic MCP SDK)
@modelcontextprotocol/ext-apps (MCP Apps SDK)
Available Tools
21 toolsgetLocalFalconCampaignReportB
Retrieves a full report of a Campaign from your Local Falcon account. Campaign reports look like https://www.localfalcon.com/campaigns/view/0ee3c5869f3fa13 where 0ee3c5869f3fa13 is the report_key.
Inputs: reportKey (required).
getLocalFalconCompetitorReportC
Retrieves up to 20 competitor businesses from a specific Competitor Report from your Local Falcon account. Competitor reports look like https://www.localfalcon.com/reports/competitor/view/08116fb5331e258 where 08116fb5331e258 is the report_key.
Inputs: reportKey (required).
getLocalFalconCompetitorReportsC
Retrieves a list of all Competitor Reports within your Local Falcon account.
Inputs: endDate, gridSize, keyword, limit, +3 more.
getLocalFalconGoogleBusinessLocationsC
Fetches Local Falcon Google Business locations.
Inputs: query (required), near, nextToken.
getLocalFalconGridC
A helper method to create a Local Falcon grid.
Inputs: gridSize (required), lat (required), lng (required), measurement (required), +1 more.
getLocalFalconGuardReportC
Retrieves a full report of a Falcon Guard Report from your Local Falcon account given a place_id.
Inputs: placeId (required).
getLocalFalconKeywordAtCoordinateC
Retrieves search results at the specified coordinate point without any rank comparison data.
Inputs: keyword (required), lat (required), lng (required), zoom.
getLocalFalconKeywordReportC
Retrieves a single Local Falcon keyword report.
Inputs: reportKey (required).
getLocalFalconLocationReportC
Retrieves a single location report. A location report looks like https://www.localfalcon.com/reports/location/view/c60c325a8665c4a where c60c325a8665c4a is the report key.
Inputs: reportKey (required).
getLocalFalconRankingAtCoordinateC
Retrieves search results at the specified coordinate point and gets ranking data for specified business.
Inputs: keyword (required), lat (required), lng (required), zoom.
getLocalFalconReportB
Retrieves a single Local Falcon scan report given a report key. Only reads the ai analysis of the returned report. Otherwise report the ai analysis is not present. Users can also enter the report key in the format of https://www.localfalcon.com/reports/view/0b38313fa35c37f where 0b38313fa35c37f is the report key.
Inputs: reportKey (required).
getLocalFalconTrendReportB
Retrieves a single Local Falcon trend report. A trend report looks like https://www.localfalcon.com/reports/trend/view/95290829819f6e8 where 95290829819f6e8 is the report key.
Inputs: reportKey (required).
listAllLocalFalconLocationsB
Retrieves a list of all locations.
Inputs: query.
listLocalFalconAutoScansC
Retrieves a list of all Auto Scans.
Inputs: frequency, grid_size, keyword, nextToken, +2 more.
listLocalFalconCampaignReportsC
Retrieves a list of all Location Reports within your Local Falcon account.
Inputs: endDate, limit, nextToken, placeId, +1 more.
listLocalFalconGuardReportsC
Retrieves a list of all Falcon Guard Reports within your Local Falcon account. This helps analyze the Google Business profile of a specific location.
Inputs: endDate, startDate.
listLocalFalconKeywordReportsC
Retrieves a list of all keyword reports. A keyword report looks like https://www.localfalcon.com/reports/keyword/view/754ffcb0f309938 where 754ffcb0f309938 is the report key.
Inputs: keyword, limit, nextToken.
listLocalFalconLocationReportsC
Retrieves a list of all location reports.
Inputs: keyword, limit, nextToken, placeId.
listLocalFalconScanReportsC
Retrieves a list of all Scan Reports performed by your Local Falcon account.
Inputs: nextToken.
listLocalFalconTrendReportsC
Retrieves a list of all Trend Reports performed by your Local Falcon account.
Inputs: keyword, limit, nextToken, placeId.
runLocalFalconFullGridSearchC
Retrieves a full grid search using the passed keyword or search term to match against the specified business.
Inputs: gridSize (required), keyword (required), lat (required), lng (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools have distinct purposes targeting specific report types or resources (e.g., Campaign, Competitor, Keyword, Location), but there is notable overlap between 'getLocalFalconReport' and other specific report getters, and 'getLocalFalconGrid' vs. 'runLocalFalconFullGridSearch' could cause confusion. Descriptions help clarify, but some ambiguity remains.
Tool names follow a consistent verb_noun pattern with 'get', 'list', or 'run' prefixes, all in camelCase. Minor deviations include 'runLocalFalconFullGridSearch' (uses 'run' instead of 'get') and 'getLocalFalconGrid' (vague noun), but overall naming is predictable and readable.
With 21 tools, the count is borderline high for a Local Falcon server, suggesting potential over-specialization or fragmentation. While it covers various report types and operations, it might feel heavy compared to typical well-scoped servers (3-15 tools), but it's not extreme.
The tool set provides comprehensive coverage for retrieving and listing various Local Falcon reports (Campaign, Competitor, Keyword, Location, etc.), with minor gaps such as lack of update or delete operations. However, for a reporting-focused domain, the CRUD lifecycle is less critical, and agents can likely work around these omissions.
Maintenance
Related MCP Connectors
Connect AI agents to your AI visibility and SEO data: competitors, citations, GSC, GA4, Bing.
Live SEO intelligence, rank tracking, site audits, and backlink analysis for AI agents.
Local business intel for AI agents: audits, lead scoring, tech stack, prospecting.
The SEO and GEO toolkit for AI agents: get new customers from Google and AI search.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates the Serpstat SEO API with the Model Context Protocol to provide AI assistants with comprehensive data for domain analysis, keyword research, and competitor tracking. It enables users to perform complex SEO tasks like backlink analysis and site audits through natural language interfaces.655MIT
- AlicenseBqualityCmaintenanceSEO intelligence tools for AI agents: SERPs, keyword research, backlinks, rank tracking, content planning, and site audits. Connect through hosted MCP or the open-source npm client. An AgentSEO account and API key are required; usage consumes credits.4590 npmMIT
- AlicenseNot gradedqualityBmaintenanceConnects AI agents to pull SERP rankings, site audit issues, AI Tracker visibility, geogrid scans, and review data from a Local Dominator account.MIT
- AlicenseNot gradedqualityBmaintenanceConnects AI agents to live SEO data and hosted tools for site audits, keyword research, competitor analysis, local SEO, and link prospecting, with guided workflows for structured search optimization.2MIT