# SerpAPI Google Trends MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides access to Google Trends data via [SerpAPI](https://serpapi.com). Perfect for analyzing regional search interest patterns to make data-driven decisions about advertising and service offerings.

Built with [FastMCP](https://github.com/jlowin/fastmcp).

## Use Case: Regional Service Marketing

This MCP server is designed to help service-based businesses answer questions like:

- **Which cities in Alabama and Missouri show the most interest in our HVAC services?**
- **Should we advertise furnace repair or heat pump services in Huntsville this winter?**
- **When does demand for heating services peak in St. Louis?**
- **What related services are customers searching for in our target markets?**

## Features

- 🗺️ **Interest by Region**: See which geographic areas have highest search interest
- 📈 **Interest Over Time**: Understand seasonal trends and timing patterns
- ⚖️ **Service Comparison**: Compare multiple services across multiple locations
- 🔍 **Related Queries**: Discover new keyword opportunities
- 📊 **Data-Driven Insights**: All data from Google Trends with 0-100 interest scale

## Installation

### Prerequisites

- Python 3.10 or higher
- SerpAPI account with API key ([Sign up here](https://serpapi.com/users/sign_up))
- Claude Desktop or Claude Code CLI

### Setup

1. **Create the directory structure**:
   ```bash
   cd serpapi-trends-mcp
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure API credentials**:
   ```bash
   cp .env.example .env
   ```

   Edit `.env` and add your SerpAPI key:
   ```
   SERPAPI_KEY=your-api-key-here
   ```

   Get your API key from: https://serpapi.com/manage-api-key

## Usage

### Claude Desktop Integration

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "serpapi-trends": {
      "command": "python",
      "args": [
        "-m",
        "serpapi_trends_mcp.server"
      ],
      "cwd": "/absolute/path/to/serpapi-trends-mcp",
      "env": {
        "SERPAPI_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code Integration

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "serpapi-trends": {
      "command": "python",
      "args": [
        "-m",
        "serpapi_trends_mcp.server"
      ],
      "cwd": "/absolute/path/to/serpapi-trends-mcp",
      "env": {
        "SERPAPI_KEY": "your-api-key-here"
      }
    }
  }
}
```

Or use command line arguments:

```json
{
  "mcpServers": {
    "serpapi-trends": {
      "command": "python",
      "args": [
        "-m",
        "serpapi_trends_mcp.server",
        "--api-key",
        "your-api-key-here"
      ],
      "cwd": "/absolute/path/to/serpapi-trends-mcp"
    }
  }
}
```

After adding the configuration, restart Claude Desktop or reconnect Claude Code.

## Available Tools

### `get_interest_by_region`

Find which geographic areas show the most interest in your services.

**Parameters**:
- `query` (required): Search term(s), comma-separated for comparison
- `date`: Time range (default: "today 3-m" for 3 months)
- `resolution`: "COUNTRY", "REGION", "CITY" (default), or "DMA"
- `geo`: Location code (e.g., "US", "US-AL", "US-MO")

**Example**:
```
Find which cities in Alabama search most for HVAC services:

get_interest_by_region(
  query="hvac repair,furnace repair,ac repair,heat pump repair",
  date="today 3-m",
  resolution="CITY",
  geo="US-AL"
)
```

### `get_interest_over_time`

Analyze how search interest changes over time to identify seasonal patterns.

**Parameters**:
- `query` (required): Search term(s), comma-separated for comparison
- `date`: Time range (default: "today 3-m")
- `geo`: Location code (e.g., "US-MO")

**Example**:
```
Compare heating vs cooling demand in Missouri over the past year:

get_interest_over_time(
  query="furnace repair,heating repair,ac repair",
  date="today 12-m",
  geo="US-MO"
)
```

### `compare_services_in_cities`

Compare multiple services across multiple regions to find the best opportunities.

**Parameters**:
- `services` (required): Comma-separated service keywords
- `cities` (required): Comma-separated region codes
- `date`: Time range (default: "today 3-m")

**Example**:
```
Compare HVAC services in Alabama and Missouri:

compare_services_in_cities(
  services="hvac repair,furnace repair,ac repair,heat pump repair",
  cities="US-AL,US-MO",
  date="today 3-m"
)
```

### `get_related_queries`

Discover related search queries to expand keyword targeting.

**Parameters**:
- `query` (required): Search term to analyze
- `date`: Time range (default: "today 3-m")
- `geo`: Location code

**Example**:
```
Find related HVAC searches in Alabama:

get_related_queries(
  query="hvac repair",
  date="today 3-m",
  geo="US-AL"
)
```

## Available Resources

Browse reference data using MCP resources:

- **`serpapi://us-states`**: List of US state codes for the geo parameter
- **`serpapi://time-ranges`**: Available time range options with recommendations

## Workflow Example: Winter Service Planning

**Scenario**: You run an HVAC company and want to decide which services to advertise in Huntsville, AL and St. Louis, MO for the upcoming winter season.

### Step 1: Compare Services by Region

```
compare_services_in_cities(
  services="furnace repair,heat pump repair,heating system,boiler repair",
  cities="US-AL,US-MO",
  date="today 3-m"
)
```

**Result**: See which cities in each state have the highest search interest.

### Step 2: Analyze Seasonal Timing

```
get_interest_over_time(
  query="furnace repair,heat pump repair",
  date="today 12-m",
  geo="US-AL"
)
```

**Result**: Identify when demand peaks (typically early winter).

### Step 3: Find Related Keywords

```
get_related_queries(
  query="furnace repair",
  date="today 3-m",
  geo="US-AL"
)
```

**Result**: Discover additional keywords like "emergency heating repair", "furnace maintenance", etc.

### Step 4: City-Level Targeting

```
get_interest_by_region(
  query="furnace repair",
  date="today 3-m",
  resolution="CITY",
  geo="US-AL"
)
```

**Result**: Get specific cities in Alabama ranked by search interest.

### Step 5: Make Data-Driven Decisions

Based on the data:
- **Budget Allocation**: Spend more on cities with higher interest scores
- **Service Focus**: Prioritize services with highest regional demand
- **Campaign Timing**: Launch ads when seasonal interest peaks
- **Keyword Expansion**: Include related queries in your targeting

## Understanding the Data

### Interest Scores (0-100 Scale)

- **100**: Peak popularity for the selected time period and location
- **50**: Half as popular as the peak
- **0**: Less than 1% of peak popularity

### Interpreting Results

- **High interest (70-100)**: Strong demand, prime target for advertising
- **Medium interest (40-69)**: Moderate opportunity, consider if competition is low
- **Low interest (0-39)**: Limited demand, may not be cost-effective

### Time Ranges Recommendations

| Use Case | Recommended Range | Code |
|----------|------------------|------|
| Current market conditions | Past 3 months | `today 3-m` |
| Full seasonal patterns | Past year | `today 12-m` |
| Long-term planning | Past 5 years | `today 5-y` |
| Recent spike analysis | Past week | `now 7-d` |

## Pricing

SerpAPI pricing is based on API calls:

- **Free tier**: 100 searches/month
- **Paid plans**: Start at $50/month for 5,000 searches
- Each tool call = 1 API search

View pricing: https://serpapi.com/pricing

## Project Structure

```
serpapi-trends-mcp/
├── src/
│   └── serpapi_trends_mcp/
│       ├── __init__.py
│       ├── server.py              # FastMCP server with tools & resources
│       └── client.py              # Async SerpAPI wrapper
├── requirements.txt               # Python dependencies
├── .env.example                   # Credential template
├── .env                          # Your credentials (gitignored)
├── .gitignore
└── README.md
```

## Development

### Testing Locally

```bash
# Run the server directly
python -m serpapi_trends_mcp.server

# Or with command line argument
python -m serpapi_trends_mcp.server --api-key YOUR_KEY

# Test with FastMCP dev mode
fastmcp dev src/serpapi_trends_mcp/server.py
```

### Adding New Tools

Edit `src/serpapi_trends_mcp/server.py` and add new `@mcp.tool` decorated functions.

### Adding New Endpoints

Edit `src/serpapi_trends_mcp/client.py` to add new SerpAPI endpoint methods.

## Troubleshooting

### "Missing SERPAPI_KEY"

- Ensure `.env` file exists with `SERPAPI_KEY=your-key`
- Or set environment variable in your shell
- Or use `--api-key` command line argument

### "401 Unauthorized"

- Verify your API key is correct
- Check you haven't exceeded your monthly quota
- Visit https://serpapi.com/manage-api-key

### "No data returned"

- Try a broader time range (e.g., "today 12-m")
- Try a less specific query term
- Some locations may have insufficient search volume

### Server not appearing in Claude Desktop

- Check the `cwd` path is absolute, not relative
- Verify Python is in your PATH
- Restart Claude Desktop after config changes
- Check Claude Desktop logs for errors

## Example Queries for HVAC Business

### Research Phase

```
"What cities in Alabama have the highest demand for HVAC services?"

"Show me search trends for heating services in Missouri over the past year"

"What related services do people search for when looking for furnace repair?"
```

### Analysis Phase

```
"Compare interest in 'heat pump repair' vs 'furnace repair' in Huntsville and St. Louis"

"When does demand for heating services peak in Alabama?"

"Which cities in Missouri show the strongest interest in emergency HVAC services?"
```

### Decision Phase

```
"Based on Google Trends, where should we focus our winter HVAC advertising budget?"

"Create a priority list of cities for our heating service marketing campaign"
```

## Resources

- [SerpAPI Documentation](https://serpapi.com/google-trends-api)
- [Google Trends Interest by Region API](https://serpapi.com/google-trends-interest-by-region)
- [Google Trends Interest Over Time API](https://serpapi.com/google-trends-interest-over-time)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)

## License

MIT License

## Support

- SerpAPI Support: https://serpapi.com/contact
- File issues: Create an issue in this repository
- MCP Documentation: https://modelcontextprotocol.io