Local Falcon MCP Server

An MCP (Model Context Protocol) server for the Local Falcon local SEO and AI Visibility platform

Local SEO and AI Visibility Monitoring MCP Server

An MCP (Model Context Protocol) server for the Local Falcon platform, implemented in TypeScript, using the official MCP SDK. This server exposes Local Falcon scanning, tracking and reporting capabilities as 37 MCP tools, enabling integration with agentic AI systems and workflows.

Features

37 MCP tools for scanning, reporting, campaign management, competitor analysis, reviews, and Falcon Guard monitoring
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
Tool annotations on all 37 tools — readOnlyHint, destructiveHint, and openWorldHint for safe auto-execution
Multi-platform — Google Maps, Apple Maps, ChatGPT, Gemini, Grok, 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.com/mcp
Set 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.com/mcp
Set 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/mcp?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE

Running 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/mcp?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 the /mcp endpoint 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/mcp

For 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.

Tools (37)

All 37 tools include MCP tool annotations that signal to AI clients whether a tool is safe to auto-execute:

Annotation	Tools	Behavior
`readOnlyHint: true`	26 tools	Read-only data retrieval — safe to auto-execute
`destructiveHint: true`	3 tools	Consumes credits or permanently removes resources — always confirm with user
`readOnlyHint: false, destructiveHint: false`	8 tools	Modifies state but reversible and free — confirm recommended
`openWorldHint: false`	All 37 tools	Tools operate within the Local Falcon platform only

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.
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.
getLocalFalconGoogleBusinessLocations: Searches Google for business listings to find Place IDs.
searchForLocalFalconBusinessLocation: Searches for business locations on Google or Apple platforms.
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.

Skills

This repo includes two AI skills under skills/:

Skill	Path	Description
Local Falcon MCP	`skills/local-falcon-mcp/`	MCP tool usage guidance — helps AI agents use the 37 MCP tools effectively
Local Visibility	`skills/local-visibility-skill/`	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 build

The build compiles TypeScript to dist/ and builds the MCP Apps UI widget to dist/ui/.

Run MCP Inspector

npm run inspector

Run 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 HTTP

License

MIT

Acknowledgments

Local Falcon API Documentation
Model Context Protocol (MCP)
@modelcontextprotocol/sdk (Anthropic MCP SDK)
@modelcontextprotocol/ext-apps (MCP Apps SDK)

Name		Name	Last commit message	Last commit date
Latest commit History 192 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
assets/icons		assets/icons
oauth		oauth
skills		skills
ui/geogrid-heatmap		ui/geogrid-heatmap
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.mcpbignore		.mcpbignore
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
index.ts		index.ts
localfalcon.ts		localfalcon.ts
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
server.ts		server.ts
tsconfig.json		tsconfig.json
vite.ui.config.ts		vite.ui.config.ts

Folders and files

Latest commit

History

Repository files navigation

Local Falcon MCP Server

Local SEO and AI Visibility Monitoring MCP Server

Features

Prerequisites

Authentication

OAuth (Recommended)

Bearer Token

API Key via Query String

Running via Remote (HTTP)

Running via Remote (SSE — Legacy)

Running via STDIO

MCP Apps

Geo-Grid Heatmap

Tools (37)

Scan Reports

Campaign Management

Reviews Analysis

Falcon Guard (GBP Monitoring)

Trend Reports

Auto Scans

Location Reports

Keyword Reports

Competitor Reports

Location Management

On-Demand Tools

Knowledge Base

Account

Skills

For Developers

Prerequisites

Build

Run MCP Inspector

Run MCP Server

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages