mcp-google-trends

chestnutforty/mcp-google-trends

3.2

If you are the rightful owner of mcp-google-trends and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Google Trends Server provides historical Google Trends data for forecasting applications, ensuring no future data leakage.

Tools
1
Resources
0
Prompts
0

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]"
  1. Configure environment variables by copying .env.example to .env:
cp .env.example .env
  1. Add your API key to .env:

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