### Development Setup

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Installs dependencies, copies the environment example, and requires adding the API key to .env.local.

```bash
npm install
cp .env.example .env.local
# Add your LOCAL_FALCON_API_KEY to .env.local
```

--------------------------------

### Install and Build Project

Source: https://github.com/local-falcon/mcp/blob/main/README.md

Installs project dependencies and compiles TypeScript to JavaScript. This is a prerequisite for running the server and developer tools.

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

--------------------------------

### Install Local Falcon MCP Server

Source: https://context7.com/local-falcon/mcp/llms.txt

Installs the Local Falcon MCP server and its dependencies. Ensure you have Node.js and npm installed. Obtain your API key from the Local Falcon website.

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

# Get your API key from https://localfalcon.com/api/credentials
```

--------------------------------

### Run Application Modes

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Commands to start the application in different modes: STDIO, SSE, HTTP, or both.

```bash
npm run start 

npm run start:sse 

npm run start:http 

npm run start:HTTPAndSSE
```

--------------------------------

### Install Local Falcon MCP Package

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-visibility-skill/SKILL.md

Use this command to install the Local Falcon MCP package via npm. Ensure you have Node.js and npm installed.

```bash
npm install @local-falcon/mcp
```

--------------------------------

### Run MCP Server

Source: https://github.com/local-falcon/mcp/blob/main/README.md

Starts the MCP server in different modes. Choose the mode based on your connectivity and authentication requirements.

```bash
npm run start             # STDIO mode (default)
```

```bash
npm run start:sse         # SSE mode with OAuth
```

```bash
npm run start:http        # HTTP mode with OAuth
```

```bash
npm run start:HTTPAndSSE  # Both SSE and HTTP
```

--------------------------------

### Install Local Falcon MCP Package

Source: https://github.com/local-falcon/mcp/blob/main/README.md

Installs the Local Falcon MCP package using npm. Ensure you are in the project directory.

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

--------------------------------

### New Location Setup and Initial Scan

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-visibility-skill/references/mcp-workflows.md

Steps to add a new business location and perform an initial visibility scan. Ensure AI analysis is enabled for comprehensive results.

```bash
1. searchForLocalFalconBusinessLocation
   → Search by business name to get Place ID
   → Parameters: query="Business Name City", platform="google"

2. saveLocalFalconBusinessLocationToAccount
   → Save location for ongoing tracking
   → Parameters: place_id from step 1

3. listLocalFalconScanReports
   → Check if any existing scan data
   → Parameters: place_id, limit=5

4. runLocalFalconScan (if no recent scans)
   → Execute initial scan
   → Parameters: place_id, keyword, grid_size, ai_analysis=true
   → ⚠️ ALWAYS enable AI Analysis Report

5. getLocalFalconReport
   → Retrieve and analyze results
   → Parameters: report_key from step 4
```

--------------------------------

### GET /local-falcon/mcp/searchLocalFalconKnowledgeBase

Source: https://context7.com/local-falcon/mcp/llms.txt

Searches the Local Falcon Knowledge Base for help articles, how-to guides, and platform documentation. Use for questions about features, settings, and best practices.

```APIDOC
## GET /local-falcon/mcp/searchLocalFalconKnowledgeBase

### Description
Searches the Local Falcon Knowledge Base for help articles, how-to guides, and platform documentation. Use for questions about features, settings, and best practices.

### Method
GET

### Endpoint
/local-falcon/mcp/searchLocalFalconKnowledgeBase

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.
- **limit** (string) - Optional - The maximum number of articles to return.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the search was successful.
- **data** (object) - The search results.
  - **articles** (array) - A list of matching articles.
    - **id** (string) - The unique identifier of the article.
    - **title** (string) - The title of the article.
    - **summary** (string) - A brief summary of the article's content.
    - **category** (string) - The category the article belongs to.

#### Response Example
{
  "success": true,
  "data": {
    "articles": [
      {
        "id": "70",
        "title": "Creating Your First Campaign",
        "summary": "Learn how to set up recurring scans across multiple locations...",
        "category": "Campaigns"
      },
      {
        "id": "71",
        "title": "Campaign Best Practices",
        "summary": "Optimize your campaign settings for maximum value...",
        "category": "Campaigns"
      }
    ]
  }
}
```

--------------------------------

### Workflow: Set up recurring monitoring

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

This workflow guides users through setting up recurring scans for ongoing monitoring of local visibility.

```APIDOC
## Workflow: Set up recurring monitoring

### Description
This workflow explains how to configure and set up recurring scans for continuous monitoring of a business's local search performance.

### Steps
1. **Verify Locations**: Use `listAllLocalFalconLocations` to ensure all target locations are saved in the account.
2. **Discuss Campaign Parameters**: Review campaign settings with the user, including frequency (daily, weekly, bi-weekly, monthly), keywords, grid size, and radius. Advise that monthly frequency is the most credit-efficient for ongoing monitoring and explain the credit implications.
3. **Create Campaign**: Use `createLocalFalconCampaign` to set up the recurring monitoring with the confirmed parameters. Note that campaign data is consolidated into a campaign report.
```

--------------------------------

### GET /local-falcon/mcp/getLocalFalconKnowledgeBaseArticle

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves the full content of a specific Knowledge Base article with step-by-step instructions.

```APIDOC
## GET /local-falcon/mcp/getLocalFalconKnowledgeBaseArticle

### Description
Retrieves the full content of a specific Knowledge Base article with step-by-step instructions.

### Method
GET

### Endpoint
/local-falcon/mcp/getLocalFalconKnowledgeBaseArticle

### Parameters
#### Query Parameters
- **articleId** (string) - Required - The ID of the article to retrieve. Can be in formats like "70", "KB70", or "article 70".

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The article content.
  - **id** (string) - The unique identifier of the article.
  - **title** (string) - The title of the article.
  - **category** (string) - The category the article belongs to.
  - **content** (string) - The full content of the article, potentially in Markdown format.

#### Response Example
{
  "success": true,
  "data": {
    "id": "70",
    "title": "Creating Your First Campaign",
    "category": "Campaigns",
    "content": "# Creating Your First Campaign\n\n## Prerequisites\n\nBefore creating a campaign...\n\n## Step 1: Navigate to Campaigns\n\n1. Log in to your Local Falcon dashboard..."
  }
}
```

--------------------------------

### Get Local Falcon Knowledge Base Article

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

Retrieve the full content of a knowledge base article using `getLocalFalconKnowledgeBaseArticle`. This provides detailed explanations and guides for using the platform.

```python
getLocalFalconKnowledgeBaseArticle(article_id='metrics-interpretation-guide')
```

--------------------------------

### MCP Server Initialization with Tools

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Demonstrates how to create an McpServer instance and register tools with MCP tool annotations. Use this pattern to set up the server with all available tools for AI agent interaction.

```typescript
getServer(sessionMapping) {
  const server = new McpServer(sessionMapping);
  server.tool(
    name,
    description,
    zodSchema,
    {
      readOnlyHint: true,
      destructiveHint: false,
    },
    handler
  );
  return server;
}
```

--------------------------------

### Workflow: Run a scan for [keyword]

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

This workflow outlines the steps and considerations for running a new local scan, including credit verification and business location management.

```APIDOC
## Workflow: Run a scan for [keyword]

### Description
This workflow details the process of initiating a new local scan, including necessary pre-checks, parameter confirmation, and execution.

### Steps
1. **Confirm with User**: Always confirm with the user before running a scan, as scans consume credits.
2. **Verify Credits**: Use `viewLocalFalconAccountInformation` to ensure sufficient credits are available.
3. **Verify Location**: Use `listAllLocalFalconLocations` to check if the business is saved. If not, use `searchForLocalFalconBusinessLocation` to find it and then `saveLocalFalconBusinessLocationToAccount` to add it.
4. **Determine Scan Parameters**: Confirm coordinates (from saved location or previous scan), grid size, and radius based on business type and service area.
5. **Run Scan**: Submit the scan request using `runLocalFalconScan` with the confirmed parameters.
6. **Poll for Report**: Periodically poll `listLocalFalconScanReports` (filtered by place ID) for the completed report. Do not retry the scan if it fails. If the report is not found after 4-5 polls, direct the user to the Local Falcon reports page.
```

--------------------------------

### Create Local Falcon Campaign

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

Set up recurring monitoring by creating a campaign with `createLocalFalconCampaign`. Specify frequency, keywords, grid size, and radius for automated scans.

```python
createLocalFalconCampaign(place_id=place_id, keyword='plumber', frequency='MONTHLY', grid_size=100, radius=15, measurement='MILES')
```

--------------------------------

### Workflow: Help me understand [feature]

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

This workflow outlines how to use the knowledge base to answer user questions about specific features.

```APIDOC
## Workflow: Help me understand [feature]

### Description
This workflow describes how to leverage the Local Falcon knowledge base to answer user inquiries about specific features.

### Steps
1. **Search Knowledge Base**: Use `searchLocalFalconKnowledgeBase` with natural language keywords related to the user's question.
2. **Retrieve Article**: Use `getLocalFalconKnowledgeBaseArticle` to fetch the full content of the relevant guide.
3. **Explain Content**: Walk the user through the retrieved information, supplementing with their specific account data where applicable.
```

--------------------------------

### GET /local-falcon/mcp/viewLocalFalconAccountInformation

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves Local Falcon account information including user details, credit balance, and subscription status.

```APIDOC
## GET /local-falcon/mcp/viewLocalFalconAccountInformation

### Description
Retrieves Local Falcon account information including user details, credit balance, and subscription status.

### Method
GET

### Endpoint
/local-falcon/mcp/viewLocalFalconAccountInformation

### Parameters
#### Query Parameters
- **returnField** (string) - Optional - Specifies which part of the account information to return. Possible values: "user", "credit package", "subscription", or "credits". If omitted, returns all available data.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The account information.
  - **user** (object) - User details.
    - **email** (string) - The user's email address.
    - **name** (string) - The user's name.
  - **credits** (object) - Credit balance information.
    - **available** (integer) - Number of available credits.
    - **used** (integer) - Number of used credits.
  - **subscription** (object) - Subscription details.
    - **plan** (string) - The subscription plan name.
    - **status** (string) - The subscription status.

#### Response Example
{
  "success": true,
  "data": {
    "user": {
      "email": "user@company.com",
      "name": "John Smith"
    },
    "credits": {
      "available": 500,
      "used": 1250
    },
    "subscription": {
      "plan": "Pro",
      "status": "active"
    }
  }
}
```

--------------------------------

### Build and Type Check

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Commands for type checking and building the project. 'npm run build' uses --noCheck for faster builds.

```bash
npx tsc --noEmit 

npm run build
```

--------------------------------

### Get Local Falcon Trend Report

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

Retrieves historical trajectory data if available. This is useful for understanding long-term performance trends.

```python
getLocalFalconTrendReport
```

--------------------------------

### Get Local Falcon Competitor Report

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves a competitor analysis report showing top-ranking businesses in the scanned area. Auto-generated with every scan.

```APIDOC
## GET /local-falcon/mcp/getLocalFalconCompetitorReport

### Description
Retrieves a competitor analysis report showing top-ranking businesses in the scanned area. Auto-generated with every scan.

### Method
GET

### Endpoint
/local-falcon/mcp/getLocalFalconCompetitorReport

### Parameters
#### Query Parameters
- **reportKey** (string) - Required - The key of the report to retrieve.
- **fieldmask** (string) - Optional - A comma-separated list of fields to include in the report. Example: "date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating"

### Response
#### Success Response (200)
- **date** (string) - The date the report was generated.
- **keyword** (string) - The keyword used for the scan.
- **grid_size** (string) - The grid size used for the scan.
- **radius** (string) - The radius used for the scan.
- **businesses** (array) - A list of top-ranking businesses.
  - **name** (string) - The name of the business.
  - **place_id** (string) - The Google Place ID of the business.
  - **arp** (string) - Average Rank Position.
  - **atrp** (string) - Average Traffic Rank Position.
  - **solv** (string) - Share of Voice Local.
  - **reviews** (string) - The number of reviews.
  - **rating** (string) - The average rating.

#### Response Example
```json
{
  "date": "2024-06-15",
  "keyword": "emergency plumber",
  "grid_size": "7",
  "radius": "5",
  "businesses": [
    {
      "name": "Top Plumbing Co",
      "place_id": "ChIJ_competitor1",
      "arp": "2.1",
      "atrp": "5.3",
      "solv": "67.3",
      "reviews": "234",
      "rating": "4.9"
    },
    {
      "name": "Joe's Plumbing",
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "arp": "3.2",
      "atrp": "8.5",
      "solv": "45.7",
      "reviews": "156",
      "rating": "4.8"
    }
  ]
}
```
```

--------------------------------

### MCPB Build Commands

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Commands to build the MCPB bundle. Ensure manifest.json is validated before packing.

```bash
npm run build 

mcpb validate manifest.json 

mcpb pack . local-falcon-mcp.mcpb
```

--------------------------------

### Build MCP App UI

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Builds the MCP App UI using npm. Ensure the GOOGLE_MAPS_API_KEY environment variable is set.

```bash
GOOGLE_MAPS_API_KEY=your-key npm run build:ui
```

--------------------------------

### Get Local Falcon Guard Report

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

Retrieves the GBP health and engagement report if Guard is enabled. This monitors profile changes and engagement metrics.

```python
getLocalFalconGuardReport
```

--------------------------------

### Execute Local Falcon Scan with AI Analysis

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-visibility-skill/references/mcp-workflows.md

This is the final step to run a scan. Ensure AI analysis is always enabled for automated insights. Platform defaults to 'google'.

```pseudocode
runLocalFalconScan:
  place_id: [from discovery]
  keyword: [suggested and confirmed]
  platform: google (default) or user's choice
  grid_size: [appropriate for business type]
  grid_distance: [appropriate for service radius]
  ai_analysis: true  ← ALWAYS ENABLE THIS
```

--------------------------------

### Get Latest Local Falcon Scan Report

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-falcon-mcp/SKILL.md

Retrieves the latest scan report for a current ranking snapshot. This is part of a full performance assessment.

```python
getLocalFalconReport
```

--------------------------------

### Docker Commands

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Commands to build and run the application within a Docker container.

```bash
npm run docker:build
npm run docker:run
```

--------------------------------

### GET /local-falcon/mcp/getLocalFalconGuardReport

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves a Falcon Guard report with GBP monitoring data. OAuth-connected locations include engagement metrics (calls, clicks, directions, impressions).

```APIDOC
## GET /local-falcon/mcp/getLocalFalconGuardReport

### Description
Retrieves a Falcon Guard report with GBP monitoring data. OAuth-connected locations include engagement metrics (calls, clicks, directions, impressions).

### Method
GET

### Endpoint
/local-falcon/mcp/getLocalFalconGuardReport

### Parameters
#### Query Parameters
- **placeId** (string) - Required - The ID of the place to retrieve the report for.
- **startDate** (string) - Required - The start date for the report (e.g., "01/01/2024").
- **endDate** (string) - Required - The end date for the report (e.g., "06/30/2024").

### Response
#### Success Response (200)
- **place_id** (string) - The ID of the place.
- **location** (object) - Information about the location.
  - **name** (string) - The name of the location.
  - **address** (string) - The address of the location.
- **status** (string) - The protection status of the location.
- **metrics** (object) - Engagement metrics for OAuth-connected locations.
  - **calls** (integer) - Number of calls.
  - **website_clicks** (integer) - Number of website clicks.
  - **direction_requests** (integer) - Number of direction requests.
  - **impressions** (integer) - Number of impressions.
- **changes** (array) - A list of changes made to the location's information.
  - **date** (string) - The date of the change.
  - **field** (string) - The field that was changed.
  - **old_value** (string) - The old value of the field.
  - **new_value** (string) - The new value of the field.

#### Response Example
{
  "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "location": {
    "name": "Joe's Plumbing",
    "address": "123 Main St, Seattle, WA"
  },
  "status": "protected",
  "metrics": {
    "calls": 245,
    "website_clicks": 892,
    "direction_requests": 156,
    "impressions": 12450
  },
  "changes": [
    {
      "date": "2024-03-15",
      "field": "hours",
      "old_value": "8:00 AM - 5:00 PM",
      "new_value": "8:00 AM - 6:00 PM"
    }
  ]
}
```

--------------------------------

### View Local Falcon Account Information

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves Local Falcon account details. Specify 'returnField' to get specific data like user, credits, or subscription.

```typescript
// MCP Tool Call - Get full account info
const accountInfo = await mcpClient.callTool("viewLocalFalconAccountInformation", {});
```

```typescript
// MCP Tool Call - Get only credits
const credits = await mcpClient.callTool("viewLocalFalconAccountInformation", {
  returnField: "credits"  // "user", "credit package", "subscription", or "credits"
});
```

```json
// Response structure
{
  "success": true,
  "data": {
    "user": {
      "email": "user@company.com",
      "name": "John Smith"
    },
    "credits": {
      "available": 500,
      "used": 1250
    },
    "subscription": {
      "plan": "Pro",
      "status": "active"
    }
  }
}
```

--------------------------------

### Running via Remote (SSE - Legacy)

Source: https://github.com/local-falcon/mcp/blob/main/README.md

This configuration uses the legacy SSE endpoint. It is recommended to use the /mcp endpoint instead for future compatibility.

```json
{
  "mcpServers": {
    "local-falcon-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.localfalcon.com/sse?local_falcon_api_key=INSERT_YOUR_API_KEY_HERE"
      ]
    }
  }
}
```

--------------------------------

### Get Local Falcon Competitor Report

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves a competitor analysis report for a given report key. The fieldmask parameter allows specifying which fields to include in the response.

```typescript
// MCP Tool Call
const competitors = await mcpClient.callTool("getLocalFalconCompetitorReport", {
  reportKey: "competitor_abc123",
  fieldmask: "date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating"
});

// Response structure
{
  "date": "2024-06-15",
  "keyword": "emergency plumber",
  "grid_size": "7",
  "radius": "5",
  "businesses": [
    {
      "name": "Top Plumbing Co",
      "place_id": "ChIJ_competitor1",
      "arp": "2.1",
      "atrp": "5.3",
      "solv": "67.3",
      "reviews": "234",
      "rating": "4.9"
    },
    {
      "name": "Joe's Plumbing",
      "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "arp": "3.2",
      "atrp": "8.5",
      "solv": "45.7",
      "reviews": "156",
      "rating": "4.8"
    }
  ]
}
```

--------------------------------

### Competitive Analysis Workflow

Source: https://github.com/local-falcon/mcp/blob/main/skills/local-visibility-skill/references/mcp-workflows.md

Understand the competitive landscape to identify opportunities. Analyzes competitor scores, reviews, and geographic coverage.

```bash
1. listAllLocalFalconLocations
   → Get target location details

2. getLocalFalconCompetitorReports
   → List available competitor analyses
   → Parameters: place_id

3. getLocalFalconCompetitorReport
   → Pull detailed competitor data
   → Parameters: report_key

4. ANALYZE:
   - Competitor SoLV scores
   - Review counts and ratings
   - Geographic coverage patterns
   - Where competitors are weak

5. IDENTIFY:
   - Opportunity corridors (low competition areas)
   - Review gaps to close
   - Keywords where you can win
```

--------------------------------

### GET /listLocalFalconCampaignReports

Source: https://context7.com/local-falcon/mcp/llms.txt

Lists campaign reports for scheduled, recurring scans. Campaigns are designed to track rankings at scale across multiple locations and/or keywords with automated scheduling.

```APIDOC
## GET /listLocalFalconCampaignReports

### Description
Lists campaign reports for scheduled, recurring scans. Campaigns track rankings at scale across multiple locations and/or keywords with automated scheduling.

### Method
GET

### Endpoint
/listLocalFalconCampaignReports

### Parameters
#### Query Parameters
- **placeId** (string) - Required - The unique identifier for the business location.
- **startDate** (string) - Optional - The start date for filtering reports (YYYY-MM-DD).
- **endDate** (string) - Optional - The end date for filtering reports (YYYY-MM-DD).
- **fieldmask** (string) - Optional - A comma-separated list of fields to include in the response. Example: "report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv".

### Request Example
```json
{
  "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "fieldmask": "report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv"
}
```

### Response
#### Success Response (200)
- **count** (integer) - The total number of campaign reports found.
- **reports** (array) - An array of campaign report objects.
  - **report_key** (string) - The unique identifier for the campaign report.
  - **name** (string) - The name of the campaign.
  - **status** (string) - The current status of the campaign (e.g., "active").
  - **locations** (integer) - The number of locations included in the campaign.
  - **keywords** (integer) - The number of keywords tracked in the campaign.
  - **frequency** (string) - The frequency of the campaign scans (e.g., "weekly").
  - **last_run** (string) - The date of the last campaign run.
  - **next_run** (string) - The date of the next scheduled campaign run.
  - **arp** (string) - Average Rank Position.
  - **atrp** (string) - Average Tracked Rank Position.
  - **solv** (string) - Search Optimization Level Value.

#### Response Example
```json
{
  "count": 3,
  "reports": [
    {
      "report_key": "campaign_abc123",
      "name": "Seattle Plumbing Keywords",
      "status": "active",
      "locations": 5,
      "keywords": 3,
      "frequency": "weekly",
      "last_run": "2024-06-15",
      "next_run": "2024-06-22",
      "arp": "4.1",
      "atrp": "9.2",
      "solv": "42.3"
    }
  ]
}
```
```

--------------------------------

### GET /listAllLocalFalconLocations

Source: https://context7.com/local-falcon/mcp/llms.txt

Lists all business locations saved in your Local Falcon account. This is useful for quickly retrieving Place IDs for businesses already in your account, avoiding additional lookups.

```APIDOC
## GET /listAllLocalFalconLocations

### Description
Lists all business locations saved in your Local Falcon account. Check here before searching Google/Apple - if the business is already saved, you get the Place ID instantly without additional lookups.

### Method
GET

### Endpoint
/listAllLocalFalconLocations

### Parameters
#### Query Parameters
- **query** (string) - Optional - A search query to filter the list of locations.

### Request Example
```json
{
  "query": "Joe's Plumbing Seattle"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the locations were retrieved successfully.
- **data** (object) - Contains the list of locations.
  - **locations** (array) - An array of location objects.
    - **place_id** (string) - The unique identifier for the business location.
    - **name** (string) - The name of the business.
    - **address** (string) - The address of the business.
    - **lat** (string) - The latitude of the business.
    - **lng** (string) - The longitude of the business.
    - **rating** (string) - The average rating of the business.
    - **reviews** (string) - The number of reviews for the business.
    - **store_code** (string) - The store code associated with the location.

#### Response Example
```json
{
  "success": true,
  "data": {
    "locations": [
      {
        "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
        "name": "Joe's Plumbing",
        "address": "123 Main St, Seattle, WA 98101",
        "lat": "47.6062",
        "lng": "-122.3321",
        "rating": "4.8",
        "reviews": "156",
        "store_code": "SEA001"
      }
    ]
  }
}
```
```

--------------------------------

### Configure MCP Server for Windows

Source: https://github.com/local-falcon/mcp/blob/main/README.md

Configuration for running the MCP server on Windows systems. Requires setting the command, arguments, and environment variables, including your API key.

```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"
      }
    }
  }
}
```

--------------------------------

### Configure Claude Desktop MCP Client

Source: https://context7.com/local-falcon/mcp/llms.txt

Configuration for connecting to the Local Falcon MCP server using the Claude Desktop client on macOS. Replace 'YOUR_USERNAME' and 'your_api_key_here' with your actual username and API key.

```json
// Claude Desktop MCP configuration (macOS)
{
  "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": "your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### GET /local-falcon/mcp/getLocalFalconReviewsAnalysisReport

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves a Reviews Analysis report with AI-powered insights including RVS (Review Volume Score), RQS (Review Quality Score), sentiment analysis, and competitor comparison.

```APIDOC
## GET /local-falcon/mcp/getLocalFalconReviewsAnalysisReport

### Description
Retrieves a Reviews Analysis report with AI-powered insights including RVS (Review Volume Score), RQS (Review Quality Score), sentiment analysis, and competitor comparison.

### Method
GET

### Endpoint
/local-falcon/mcp/getLocalFalconReviewsAnalysisReport

### Parameters
#### Query Parameters
- **reportKey** (string) - Required - The key of the report to retrieve.

### Response
#### Success Response (200)
- **report_key** (string) - The key of the report.
- **location** (object) - Information about the location.
  - **name** (string) - The name of the location.
- **date** (string) - The date the report was generated.
- **statistics** (object) - Analysis statistics.
  - **metrics** (object) - Primary business metrics.
    - **primaryBusiness** (object)
      - **rvs** (float) - Review Volume Score.
      - **rqs** (float) - Review Quality Score.
      - **total_reviews** (integer) - Total number of reviews.
      - **average_rating** (float) - Average rating.
      - **review_velocity** (float) - Review velocity.
      - **review_freshness** (float) - Review freshness.
      - **response_rate** (float) - Review response rate.
  - **sentiment** (object) - Sentiment analysis of reviews.
    - **positive** (float) - Percentage of positive sentiment.
    - **neutral** (float) - Percentage of neutral sentiment.
    - **negative** (float) - Percentage of negative sentiment.
  - **topics** (array) - Analysis of topics mentioned in reviews.
    - **topic** (string) - The topic discussed.
    - **mentions** (integer) - Number of mentions for the topic.
    - **sentiment** (float) - Sentiment score for the topic.

#### Response Example
{
  "report_key": "reviews_abc123",
  "location": { "name": "Joe's Plumbing" },
  "date": "2024-06-15",
  "statistics": {
    "metrics": {
      "primaryBusiness": {
        "rvs": 78.5,
        "rqs": 82.3,
        "total_reviews": 156,
        "average_rating": 4.8,
        "review_velocity": 8.2,
        "review_freshness": 0.85,
        "response_rate": 0.72
      }
    },
    "sentiment": {
      "positive": 0.82,
      "neutral": 0.12,
      "negative": 0.06
    },
    "topics": [
      { "topic": "Service Quality", "mentions": 89, "sentiment": 0.91 },
      { "topic": "Response Time", "mentions": 45, "sentiment": 0.88 },
      { "topic": "Pricing", "mentions": 32, "sentiment": 0.65 }
    ]
  }
}
```

--------------------------------

### Tool Annotations

Source: https://github.com/local-falcon/mcp/blob/main/CLAUDE.md

Information on tool annotations for AI client execution guidance.

```APIDOC
## Tool Annotations

Every `server.tool()` call includes an MCP tool annotations object that tells AI clients whether the tool is safe to auto-execute or should require user confirmation. These are placed after the Zod input schema and before the handler callback.

### Read-Only Tools — `{ readOnlyHint: true }`

These tools only retrieve data. They never modify state, create resources, or cost credits.

Includes all 20 report list/get tools, plus: `listAllLocalFalconLocations`, `getLocalFalconGoogleBusinessLocations`, `getLocalFalconGrid`, `getLocalFalconRankingAtCoordinate`, `getLocalFalconKeywordAtCoordinate`, `viewLocalFalconAccountInformation`, `searchForLocalFalconBusinessLocation`, `searchLocalFalconKnowledgeBase`, `getLocalFalconKnowledgeBaseArticle`.

### Destructive / Credit-Consuming Tools — `{ destructiveHint: true }`

These tools consume credits (irreversible) or permanently remove resources. AI clients should always confirm with the user before executing.

- `runLocalFalconScan`: Costs credits
- `runLocalFalconCampaign`: Costs credits
- `removeFalconGuardProtection`: Permanently removes Guard monitoring
```

--------------------------------

### Get Local Falcon Trend Report

Source: https://context7.com/local-falcon/mcp/llms.txt

Retrieves a trend report showing historical ARP, ATRP, and SoLV changes over time. Auto-generated when 2+ scans exist with identical settings.

```APIDOC
## GET /local-falcon/mcp/getLocalFalconTrendReport

### Description
Retrieves a trend report showing historical ARP, ATRP, and SoLV changes over time. Auto-generated when 2+ scans exist with identical settings.

### Method
GET

### Endpoint
/local-falcon/mcp/getLocalFalconTrendReport

### Parameters
#### Query Parameters
- **reportKey** (string) - Required - The key of the report to retrieve.
- **fieldmask** (string) - Optional - A comma-separated list of fields to include in the report. Example: "report_key,keyword,location.name,scan_count,scans.*.date,scans.*.arp,scans.*.atrp,scans.*.solv"

### Response
#### Success Response (200)
- **report_key** (string) - The key of the trend report.
- **keyword** (string) - The keyword used for the scans.
- **location** (object) - Information about the location.
  - **name** (string) - The name of the location.
- **scan_count** (integer) - The total number of scans included in the report.
- **scans** (array) - A list of historical scan data.
  - **date** (string) - The date of the scan.
  - **arp** (string) - Average Rank Position for the scan.
  - **atrp** (string) - Average Traffic Rank Position for the scan.
  - **solv** (string) - Share of Voice Local for the scan.

#### Response Example
```json
{
  "report_key": "trend_abc123",
  "keyword": "emergency plumber",
  "location": { "name": "Joe's Plumbing" },
  "scan_count": 6,
  "scans": [
    { "date": "2024-01-15", "arp": "4.5", "atrp": "12.1", "solv": "32.5" },
    { "date": "2024-02-15", "arp": "4.2", "atrp": "11.3", "solv": "35.2" },
    { "date": "2024-03-15", "arp": "3.8", "atrp": "9.8", "solv": "40.1" },
    { "date": "2024-04-15", "arp": "3.5", "atrp": "9.1", "solv": "43.8" },
    { "date": "2024-05-15", "arp": "3.3", "atrp": "8.7", "solv": "44.9" },
    { "date": "2024-06-15", "arp": "3.2", "atrp": "8.5", "solv": "45.7" }
  ]
}
```
```