{"id":47712212,"url":"https://github.com/local-falcon/mcp","last_synced_at":"2026-04-02T18:39:26.471Z","repository":{"id":293112720,"uuid":"982977090","full_name":"local-falcon/mcp","owner":"local-falcon","description":"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","archived":false,"fork":false,"pushed_at":"2026-03-30T01:15:50.000Z","size":694,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-30T01:36:58.707Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://www.localfalcon.com/features/mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/local-falcon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-13T17:29:33.000Z","updated_at":"2026-03-30T01:11:38.000Z","dependencies_parsed_at":"2025-08-09T22:00:49.772Z","dependency_job_id":null,"html_url":"https://github.com/local-falcon/mcp","commit_stats":null,"previous_names":["local-falcon/mcp"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/local-falcon/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/local-falcon%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/local-falcon%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/local-falcon%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/local-falcon%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/local-falcon","download_url":"https://codeload.github.com/local-falcon/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/local-falcon%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-04-02T18:39:25.798Z","updated_at":"2026-04-02T18:39:26.462Z","avatar_url":"https://github.com/local-falcon.png","language":"TypeScript","funding_links":[],"categories":[":globe_with_meridians: MCP Servers"],"sub_categories":[":round_pushpin: Local SEO"],"readme":"# Local Falcon MCP Server\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://www.localfalcon.com/uploads/identity/logos/742656_falcon-ai-logo.svg\" alt=\"Local Falcon\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAn MCP (Model Context Protocol) server for the Local Falcon local SEO and AI Visibility platform\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@local-falcon/mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@local-falcon/mcp.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/local-falcon/mcp/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg\" alt=\"Node.js\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.8-blue.svg\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.localfalcon.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Local%20Falcon-Website-red\" alt=\"Local Falcon\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.localfalcon.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/API%20Docs-docs.localfalcon.com-green\" alt=\"API Docs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Local SEO and AI Visibility Monitoring MCP Server\n\nAn 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.\n\n---\n\n## Features\n\n- **37 MCP tools** for scanning, reporting, campaign management, competitor analysis, reviews, and Falcon Guard monitoring\n- **Interactive MCP Apps widget** — geo-grid heatmap with Google Maps, colored rank pins, and clickable detail panels\n- **OAuth 2.1** with PKCE, refresh token support, and dynamic client registration\n- **Tool annotations** on all 37 tools — `readOnlyHint`, `destructiveHint`, and `openWorldHint` for safe auto-execution\n- **Multi-platform** — Google Maps, Apple Maps, ChatGPT, Gemini, Grok, Google AI Overviews, AI Mode\n- **ChatGPT MCP connector compatible** — OAuth scope alignment, widget sandbox domain, structured content parsing\n- **HTML sanitizer** for AI scrape content displayed in the heatmap widget\n\n---\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) (install the LTS version)\n\n## Authentication\n\n### OAuth (Recommended)\n\nOAuth 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.\n\n1. Set the URL to `https://mcp.localfalcon.com/mcp`\n2. Set **Authentication** to **OAuth**\n3. Leave **Client ID** and **Client Secret** empty — the server handles client registration automatically\n4. Connect and authorize when redirected to Local Falcon\n\n### Bearer Token\n\nIf your MCP client does not support OAuth, you can use your Local Falcon API key as a Bearer token.\n\n1. Set the URL to `https://mcp.localfalcon.com/mcp`\n2. Set **Authentication** to **Bearer Token**\n3. Enter your Local Falcon API key as the token value\n\n### API Key via Query String\n\nIf your MCP client does not support OAuth or Bearer Token authentication, you can pass your API key directly in the URL:\n\n```\nhttps://mcp.localfalcon.com/mcp?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE\n```\n\n---\n\n## Running via Remote (HTTP)\n\nFor MCP clients that use `mcp-remote` (all platforms):\n\n```json\n{\n  \"mcpServers\": {\n    \"local-falcon-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp.localfalcon.com/mcp?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE\"\n      ]\n    }\n  }\n}\n```\n\n## Running via Remote (SSE — Legacy)\n\n**The /sse endpoint is considered legacy and will be removed in a future version. Use the /mcp endpoint instead.**\n\n```json\n{\n  \"mcpServers\": {\n    \"local-falcon-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp.localfalcon.com/sse?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE\"\n      ]\n    }\n  }\n}\n```\n\n## Running via STDIO\n\n**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.\n\nFor local installations, first install the package:\n\n```bash\nmkdir lf-mcp\ncd lf-mcp\nnpm i @local-falcon/mcp\n```\n\nFor MacOS/Unix:\n```json\n{\n  \"mcpServers\": {\n    \"local-falcon-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/Users/YOUR_USERNAME/lf-mcp/node_modules/@local-falcon/mcp/dist/index.js\"],\n      \"env\": {\n        \"LOCAL_FALCON_API_KEY\": \"INSERT_YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nFor Windows:\n```json\n{\n  \"mcpServers\": {\n    \"local-falcon-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\YOUR_USERNAME\\\\lf-mcp\\\\node_modules\\\\@local-falcon\\\\mcp\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"LOCAL_FALCON_API_KEY\": \"INSERT_YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## MCP Apps\n\nThe 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).\n\n### Geo-Grid Heatmap\n\nWhen you call `getLocalFalconReport`, clients that support MCP Apps will display an interactive geo-grid heatmap widget featuring:\n\n- **Metrics bar** — keyword, business name, grid size, ARP, ATRP, SoLV, scan date\n- **Google Maps** — full interactive map with colored rank pins (green = rank 1, red = rank 9+)\n- **Detail panel** — click any pin to see the full business listing at that grid point with ratings, reviews, categories, and AI scrape content\n- **HTML sanitizer** — AI scrape content is sanitized with an allowlist of safe tags, attributes, and image domains before rendering\n\nThe widget is built as a single-file HTML application using Vite and served as an MCP App resource.\n\n---\n\n## Tools (37)\n\nAll 37 tools include MCP tool annotations that signal to AI clients whether a tool is safe to auto-execute:\n\n| Annotation | Tools | Behavior |\n|---|---|---|\n| `readOnlyHint: true` | 26 tools | Read-only data retrieval — safe to auto-execute |\n| `destructiveHint: true` | 3 tools | Consumes credits or permanently removes resources — always confirm with user |\n| `readOnlyHint: false, destructiveHint: false` | 8 tools | Modifies state but reversible and free — confirm recommended |\n| `openWorldHint: false` | All 37 tools | Tools operate within the Local Falcon platform only |\n\n### Scan Reports\n* **listLocalFalconScanReports**: Lists all existing scan reports. Check here first before running new scans to avoid duplicates.\n* **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.\n* **runLocalFalconScan**: Runs a new scan at the specified coordinates to get ranking data for a business.\n\n### Campaign Management\n* **listLocalFalconCampaignReports**: Lists all campaign reports. Campaigns track rankings at scale with scheduled scans.\n* **getLocalFalconCampaignReport**: Retrieves a specific campaign report (e.g., `https://www.localfalcon.com/campaigns/view/XXXXX`).\n* **createLocalFalconCampaign**: Creates a new campaign with scheduled recurring scans.\n* **runLocalFalconCampaign**: Manually triggers a campaign to run immediately.\n* **pauseLocalFalconCampaign**: Pauses a campaign's scheduled runs.\n* **resumeLocalFalconCampaign**: Resumes a paused campaign.\n* **reactivateLocalFalconCampaign**: Reactivates a campaign deactivated due to insufficient credits.\n\n### Reviews Analysis\n* **listLocalFalconReviewsAnalysisReports**: Lists all Reviews Analysis reports with AI-powered review insights.\n* **getLocalFalconReviewsAnalysisReport**: Retrieves a specific Reviews Analysis report.\n\n### Falcon Guard (GBP Monitoring)\n* **listLocalFalconGuardReports**: Lists Falcon Guard reports for monitored locations.\n* **getLocalFalconGuardReport**: Retrieves a specific Falcon Guard report by place_id.\n* **addLocationsToFalconGuard**: Adds locations to Falcon Guard protection.\n* **pauseFalconGuardProtection**: Pauses protection for specified locations.\n* **resumeFalconGuardProtection**: Resumes protection for paused locations.\n* **removeFalconGuardProtection**: Removes locations from Falcon Guard entirely.\n\n### Trend Reports\n* **listLocalFalconTrendReports**: Lists auto-generated trend reports showing ranking changes over time.\n* **getLocalFalconTrendReport**: Retrieves a specific trend report (e.g., `https://www.localfalcon.com/reports/trend/view/XXXXX`).\n\n### Auto Scans\n* **listLocalFalconAutoScans**: Lists individually scheduled automatic scans (not campaign-based).\n\n### Location Reports\n* **listLocalFalconLocationReports**: Lists auto-generated reports aggregating scans for specific locations.\n* **getLocalFalconLocationReport**: Retrieves a specific location report (e.g., `https://www.localfalcon.com/reports/location/view/XXXXX`).\n\n### Keyword Reports\n* **listLocalFalconKeywordReports**: Lists auto-generated reports aggregating scans for specific keywords.\n* **getLocalFalconKeywordReport**: Retrieves a specific keyword report (e.g., `https://www.localfalcon.com/reports/keyword/view/XXXXX`).\n\n### Competitor Reports\n* **getLocalFalconCompetitorReports**: Lists auto-generated competitor analysis reports.\n* **getLocalFalconCompetitorReport**: Retrieves a specific competitor report (e.g., `https://www.localfalcon.com/reports/competitor/view/XXXXX`).\n\n### Location Management\n* **listAllLocalFalconLocations**: Lists all business locations saved in your account.\n* **getLocalFalconGoogleBusinessLocations**: Searches Google for business listings to find Place IDs.\n* **searchForLocalFalconBusinessLocation**: Searches for business locations on Google or Apple platforms.\n* **saveLocalFalconBusinessLocationToAccount**: Saves a business location to your account.\n\n### On-Demand Tools\n* **getLocalFalconGrid**: Helper tool that generates grid coordinates for single-point checks.\n* **getLocalFalconRankingAtCoordinate**: Single-point ranking check at one coordinate.\n* **getLocalFalconKeywordAtCoordinate**: Single-point keyword search at one coordinate.\n\n### Knowledge Base\n* **searchLocalFalconKnowledgeBase**: Searches the Local Falcon Knowledge Base for help articles, how-to guides, and platform documentation.\n* **getLocalFalconKnowledgeBaseArticle**: Retrieves the full content of a specific Knowledge Base article by ID.\n\n### Account\n* **viewLocalFalconAccountInformation**: Retrieves account info including user, credits, and subscription details.\n\n---\n\n## Skills\n\nThis repo includes two AI skills under `skills/`:\n\n| Skill | Path | Description |\n|---|---|---|\n| **Local Falcon MCP** | `skills/local-falcon-mcp/` | MCP tool usage guidance — helps AI agents use the 37 MCP tools effectively |\n| **Local Visibility** | `skills/local-visibility-skill/` | General AI visibility \u0026 local SEO strategy — platform analysis, metrics interpretation, prompt templates |\n\n---\n\n## For Developers\n\n\u003e **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.\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) 18+ (LTS recommended)\n- npm (included with Node.js)\n\n### Build\n\n```bash\nnpm install\nnpm run build\n```\n\nThe build compiles TypeScript to `dist/` and builds the MCP Apps UI widget to `dist/ui/`.\n\n### Run MCP Inspector\n\n```bash\nnpm run inspector\n```\n\n### Run MCP Server\n\n```bash\nnpm run start             # STDIO mode (default)\nnpm run start:sse         # SSE mode with OAuth\nnpm run start:http        # HTTP mode with OAuth\nnpm run start:HTTPAndSSE  # Both SSE and HTTP\n```\n\n\n---\n\n\n## License\n\nMIT\n\n---\n\n## Acknowledgments\n- [Local Falcon API Documentation](https://docs.localfalcon.com)\n- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol)\n- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) (Anthropic MCP SDK)\n- [@modelcontextprotocol/ext-apps](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) (MCP Apps SDK)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocal-falcon%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocal-falcon%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocal-falcon%2Fmcp/lists"}