README.md•4.6 kB
# 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.
## Testing
### Setup
1. Install test dependencies:
```bash
uv pip install -e ".[test]"
```
2. Configure environment variables by copying `.env.example` to `.env`:
```bash
cp .env.example .env
```
3. Add your API key to `.env`:
- `SERPAPI_API_KEY` - Required from https://serpapi.com/
### Running Tests
Run all tests:
```bash
pytest
```
Run with verbose output:
```bash
pytest -v
```
Run specific test file:
```bash
pytest tests/test_google_trends_server.py
```
Run specific test:
```bash
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