Metadata-Version: 2.4
Name: niche-google-trends-mcp
Version: 0.3.0
Summary: MCP server for Google Trends keyword validation and demand analysis. No API key needed.
Project-URL: Homepage, https://github.com/duanchao/niche-demand-discovery
Project-URL: Repository, https://github.com/duanchao/niche-demand-discovery
Author: duanchao
License-Expression: Apache-2.0
Keywords: demand-discovery,google-trends,indie-hacker,mcp,niche
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: mcp>=2.0.0
Requires-Dist: patchright>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# niche-google-trends-mcp

MCP server for Google Trends keyword validation and demand analysis. **No API key needed.**

v0.2.0 — Replaces broken pytrends backend with real Chrome browser + RSS feed.

## How it works

| Tool | Backend | Description |
|------|---------|-------------|
| `trends_interest_over_time` | Chrome browser | Keyword interest over time (0-100 scale) |
| `trends_related_queries` | Chrome browser | Related and rising queries |
| `trends_compare` | Chrome browser | Compare interest across keywords |
| `trends_trending_searches` | RSS feed | Today's real-time trending searches |

**Browser tools** launch a real Chrome via CDP (port 9223), navigate to `trends.google.com/trends/explore`, and **intercept the API responses** from:

- `/trends/api/widgetdata/multiline` → timeline data
- `/trends/api/widgetdata/relatedsearches` → related queries
- `/trends/api/widgetdata/comparedgeo` → geographic data

This bypasses pytrends 429 issues entirely by routing through a real browser session.

**RSS** fetches from the public Google Trends RSS feed (`trends.google.com/trending/rss`). Always available.

## Setup

```bash
# Install
pip install niche-google-trends-mcp
# or
uvx niche-google-trends-mcp

# First-time setup: open Chrome and accept Google cookies
niche-google-trends-mcp --login
```

## MCP Config

```json
{
  "mcpServers": {
    "niche-google-trends-mcp": {
      "command": "uvx",
      "args": ["niche-google-trends-mcp"]
    }
  }
}
```

## Architecture

```
src/google_trends_mcp/
├── server.py          # FastMCP with 4 tools + CLI
├── tools.py           # Pydantic params + async routing
├── rss.py             # Google Trends RSS fetcher  
└── browser/
    ├── __init__.py
    ├── client.py      # TrendsBrowser via Patchright/CDP
    └── scraper.py     # API response interception + parsing
```

## Key differences from v0.1.0 (pytrends)

| | v0.1.0 (pytrends) | v0.2.0 (Patchright + RSS) |
|---|---|---|
| Backend | pytrends scraper | Real Chrome browser + RSS |
| 429 issues | Constant | Rare (retry logic built in) |
| API key | None | None |
| Dependencies | `pytrends`, `pandas` | `patchright` (no pandas) |
| Data extraction | HTTP calls | Network response interception |

## Rate limiting

Google rate-limits the `widgetdata/multiline` and `relatedsearches` endpoints. The code handles this with:

- 2 retries with 10s/20s exponential backoff
- `parse_jsonp()` returns `None` for non-JSON responses (HTML error pages)
- RSS `trending_searches` is never rate-limited

## Testing

```bash
# Unit tests (no Chrome needed)
uv run pytest tests/ -v

# Integration test (requires Chrome on port 9223)
uv run python scripts/integration_test.py
```
