MCP Google Trends Server

MCP server providing Google Trends search interest data with backtesting support via cutoff date filtering.

Overview

This server provides a tool to retrieve Google Trends data for any search query over a 30-day period ending at a specified cutoff date. It's designed for forecasting applications that require historical search interest data without future information leakage.

Features

• Backtesting Compliant: All data is strictly filtered to before the cutoff date
• 30-Day Windows: Retrieves search interest trends for the 30 days before cutoff
• US Region: Currently configured for US search interest data
• 0-100 Scale: Returns normalized interest scores where 100 = peak popularity

Tools

get_google_trends

Get Google Trends data for a query over the past 30 days before a cutoff date.

Parameters:

• query (str): The search query to analyze trends for
• cutoff_date (str): ISO format date (YYYY-MM-DD) - retrieve trends data ending at this date

Returns:

• Formatted string with:
  • Query term
  • Time period (30 days before cutoff_date to cutoff_date)
  • Region (US)
  • Interest over time data (0-100 scale)
  • Marks partial data entries

Example:

result = await get_google_trends(
    query="artificial intelligence",
    cutoff_date="2024-06-01"
)
# Returns trends from 2024-05-02 to 2024-06-01

Environment Variables

Required:

• SERPAPI_API_KEY: API key for SerpAPI Google Trends access

Get your API key at: https://serpapi.com/

Installation

cd mcp-google-trends
uv sync

Usage

Testing Locally

mcp run -t sse google_trends_server.py:mcp

As Git Submodule

git submodule add <repo-url> mcp-servers/mcp-google-trends

Backtesting Compliance

This server is designed for use in forecasting applications that require strict temporal boundaries:

1. Date Range Enforcement: The 30-day window is calculated from the cutoff_date backwards
2. API-Level Filtering: Date constraints are passed directly to SerpAPI's Google Trends engine
3. No Future Data: All returned data points are guaranteed to be from before the cutoff_date

This makes it safe to use in backtesting scenarios where you're simulating predictions made at historical points in time.

Testing

Setup

1. Install test dependencies:

uv pip install -e ".[test]"

2. Configure environment variables by copying .env.example to .env:

cp .env.example .env

3. Add your API key to .env:
   • SERPAPI_API_KEY - Required from https://serpapi.com/

Running Tests

Run all tests:

pytest

Run with verbose output:

pytest -v

Run specific test file:

pytest tests/test_google_trends_server.py

Run specific test:

pytest tests/test_google_trends_server.py::test_get_google_trends_basic -v

Test Coverage

The test suite covers:

• Basic functionality: Standard Google Trends queries with various topics
• Date handling: Different cutoff dates (recent, historical, future, invalid)
• Query types: Single words, multi-word phrases, brands, special characters, numeric queries
• Output format: Verification of all expected sections (header, period, region, data points)
• Date range: Validation of 30-day lookback window
• Error handling: Invalid date formats, malformed dates
• Region info: Verification of US region specification

Note: Tests make real API calls to SerpAPI and require a valid SERPAPI_API_KEY. Tests will be skipped if the API key is not set. API rate limits and costs may apply.

Dependencies

• fastmcp: MCP server framework
• serpapi: SerpAPI Python client for Google Trends access
• python-dotenv: Environment variable management

API Details

Uses SerpAPI's Google Trends engine with the following parameters:

• data_type: "TIMESERIES" - returns time-series data
• geo: "US" - United States region
• tz: 0 - UTC timezone
• date: Date range in format "{start_date} {end_date}"

Error Handling

The tool returns user-friendly error messages for common issues:

• Invalid date format (not YYYY-MM-DD)
• Missing SERPAPI_API_KEY
• API request failures
• No data found for query

All errors are returned as strings rather than raising exceptions, making integration more predictable.

Limitations

• Currently configured for US region only (can be extended to other regions)
• Fixed 30-day lookback window (can be made configurable)
• Requires active SerpAPI subscription with Google Trends access