npm package: @loc-ai/mcp-server
Description: MCP server for remote local seo automation using Loc.ai
Author: Loc.ai
Latest version: 0.2.0

# @loc-ai/mcp-server

A Model Context Protocol server that provides SEO and local search analytics capabilities. This MCP server enables large language models to analyze search volumes, domain keywords, locations, and rankings without requiring complex API integrations.

## Features

- **Keyword Analytics**: Get search volume data for keywords in specific cities and DMAs
- **Domain Intelligence**: Discover top keywords for any domain
- **Location Data**: Retrieve all business locations for a given domain
- **Ranking Analysis**: Access comprehensive ranking data including GMB ratings
- **Local SEO Insights**: Analyze keyword rankings in specific Designated Market Areas (DMAs)

## Tools

| Tool Name | Description | Required Parameters |
|-----------|-------------|---------------------|
| `get_keyword_search_volume` | Get search volume of a keyword in a city's DMA | `keyword`, `city` |
| `get_domain_keywords` | Get keywords for a domain | `domain` |
| `get_domain_locations` | Get all locations of a domain | `domain` |
| `get_domain_rankings` | Get rankings of a domain with GMB ratings | `domain` |
| `get_location_rankings` | Get keyword rankings for a location in a DMA | `location`, `dma` |

## Configuration

### Environment Variables

The @loc-ai/mcp-server requires the following environment variable:

- `LOC_AI_API_KEY`: Your Loc AI API key (required). Sign up at https://loc.ai to get your API key.

### NPX Configuration

Add this to your `.mcprc` file:

```json
{
  "mcpServers": {
    "loc-ai": {
      "command": "npx",
      "args": ["-y", "@loc-ai/mcp-server"],
      "env": {
        "LOC_AI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Data Models

### Keyword Search Volume

```typescript
interface KeywordSearchVolume {
  keyword: string;
  dma: string;
  city: string;
  monthlySearchVolume: number;
  competition: 'low' | 'medium' | 'high';
  cpc: number;
}
```

### Domain Keywords

```typescript
interface DomainKeyword {
  keyword: string;
  position: number;
  searchVolume: number;
  cpc: number;
  competition: 'low' | 'medium' | 'high';
  difficulty: number;
}
```

### Domain Locations

```typescript
interface DomainLocation {
  id: string;
  name: string;
  address: string;
  city: string;
  state: string;
  zipCode: string;
  dma: string;
  latitude: number;
  longitude: number;
  phone: string;
  website: string;
}
```

### Domain Rankings

```typescript
interface DomainRanking {
  domain: string;
  overallRank: number;
  organicVisibility: number;
  organicKeywords: number;
  paidVisibility: number;
  paidKeywords: number;
  backlinks: number;
  gmbRating: 'good' | 'average' | 'poor';
  localRankings: {
    dma: string;
    position: number;
    keywordCount: number;
  }[];
}
```

### Location Keywords Rankings

```typescript
interface LocationKeywordRanking {
  location: string;
  dma: string;
  keywords: {
    keyword: string;
    position: number;
    searchVolume: number;
    competitionLevel: 'low' | 'medium' | 'high';
  }[];
}
```

## Example Usage

When properly configured in your model, you can use commands like:

```
Get the search volume for "dentist near me" in Chicago
```

```
Show me the top keywords for apple.com
```

```
List all locations for bestbuy.com
```

```
What are the rankings for target.com?
```

```
Show keyword rankings for "New York Store" in the New York DMA
```

## Development

### Setup

1. Install dependencies:
```bash
npm install
```

2. Compile TypeScript:
```bash
npx tsc
```

3. Run the server:
```bash
node dist/index.js
```

### Implementation Details

The server is organized into several logical components:

1. **Type Definitions**: TypeScript interfaces for all data structures
2. **Tool Definitions**: MCP protocol tool specifications
3. **API Service Layer**: Handles communication with the Loc AI API
4. **Tool Handlers**: Processes tool requests from the language model
5. **Server Setup**: MCP server configuration

## License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.