serpapi-mcp-server by geopopos - MCP Server

SerpAPI Google Trends MCP Server

A Model Context Protocol (MCP) server that provides access to Google Trends data via SerpAPI. Perfect for analyzing regional search interest patterns to make data-driven decisions about advertising and service offerings.

Built with 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)
Claude Desktop or Claude Code CLI

Setup

Create the directory structure:
```
cd serpapi-trends-mcp
```
Install dependencies:
```
pip install -r requirements.txt
```
Configure API credentials:
```
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

{
  "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:

{
  "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:

{
  "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

# 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"

geopopos/serpapi-mcp-server

SerpAPI Google Trends MCP Server

Use Case: Regional Service Marketing

Features

Installation

Prerequisites

Setup

Usage

Claude Desktop Integration

Claude Code Integration

Available Tools

get_interest_by_region

get_interest_over_time

compare_services_in_cities

get_related_queries

Available Resources

Workflow Example: Winter Service Planning

Step 1: Compare Services by Region

Step 2: Analyze Seasonal Timing

Step 3: Find Related Keywords

Step 4: City-Level Targeting

Step 5: Make Data-Driven Decisions

Understanding the Data

Interest Scores (0-100 Scale)

Interpreting Results

Time Ranges Recommendations

Pricing

Project Structure

Development

Testing Locally

Adding New Tools

Adding New Endpoints

Troubleshooting

"Missing SERPAPI_KEY"

"401 Unauthorized"

"No data returned"

Server not appearing in Claude Desktop

Example Queries for HVAC Business

Research Phase

Analysis Phase

Decision Phase

Resources

License

Support

`get_interest_by_region`

`get_interest_over_time`

`compare_services_in_cities`

`get_related_queries`