MCP Google Trends Server

Metadata-Version: 2.4 Name: mcp-google-trends Version: 0.1.0 Summary: MCP server for Google Trends data retrieval Requires-Python: <3.13,>=3.12 Description-Content-Type: text/markdown Requires-Dist: fastmcp Requires-Dist: serpapi Requires-Dist: python-dotenv # 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:** ```python 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 ```bash cd mcp-google-trends uv sync ``` ## Usage ### Testing Locally ```bash mcp run -t sse google_trends_server.py:mcp ``` ### As Git Submodule ```bash 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. ## 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