https://github.com/local-falcon/mcp

MCP server for Local Falcon's local SEO and AI visibility platform: geo-grid rank tracking, campaign management, and competitor analysis via Model Context Protocol
https://github.com/local-falcon/mcp

ai-search-optimization ai-seo ai-seo-tools ai-visibility analytics api artificial-intelligence connector gbp geogrid google-business-profile local-falcon local-seo mcp model-context-protocol oauth2 rank-tracking saiv solv

Last synced: 2 months ago
JSON representation

MCP server for Local Falcon's local SEO and AI visibility platform: geo-grid rank tracking, campaign management, and competitor analysis via Model Context Protocol

Host: GitHub
URL: https://github.com/local-falcon/mcp
Owner: local-falcon
License: mit
Created: 2025-05-13T17:29:33.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2026-03-30T01:15:50.000Z (3 months ago)
Last Synced: 2026-03-30T01:36:58.707Z (3 months ago)
Topics: ai-search-optimization, ai-seo, ai-seo-tools, ai-visibility, analytics, api, artificial-intelligence, connector, gbp, geogrid, google-business-profile, local-falcon, local-seo, mcp, model-context-protocol, oauth2, rank-tracking, saiv, solv
Language: TypeScript
Homepage: https://www.localfalcon.com/features/mcp
Size: 678 KB
Stars: 15
Watchers: 1
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-seo-mcp-servers - local-falcon-mcp - grid rank tracking, GBP monitoring, competitor analysis | (:globe_with_meridians: MCP Servers / :round_pushpin: Local SEO)

README

# 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](https://www.localfalcon.com/), 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](https://nodejs.org/) (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.

1. Set the URL to `https://mcp.localfalcon.com/mcp`
2. Set **Authentication** to **OAuth**
3. Leave **Client ID** and **Client Secret** empty — the server handles client registration automatically
4. 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.

1. Set the URL to `https://mcp.localfalcon.com/mcp`
2. Set **Authentication** to **Bearer Token**
3. 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):

```json
{
"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.**

```json
{
"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](https://github.com/local-falcon/mcp/releases) and open it in Claude Desktop. For manual installation, follow the steps below.

For local installations, first install the package:

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

For MacOS/Unix:
```json
{
"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:
```json
{
"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](https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/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](https://nodejs.org/) (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](https://nodejs.org/) 18+ (LTS recommended)
- npm (included with Node.js)

### Build

```bash
npm install
npm run build
```

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

### Run MCP Inspector

```bash
npm run inspector
```

### Run MCP Server

```bash
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](https://docs.localfalcon.com)
- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol)
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) (Anthropic MCP SDK)
- [@modelcontextprotocol/ext-apps](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) (MCP Apps SDK)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/local-falcon/mcp

Awesome Lists containing this project

README