Skip to content
Back to search

google-trends-mcp

An MCP server (FastMCP, stdio) that turns Google Trends into an editorial research tool for AI agents: find out what a country started searching for in the last few hours, check whether a keyword has real and sustained demand, and collect the source articles behind a trend, all before writing a single word.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/john-of--google-trends-mcp/badge.svg)](/listings/john-of--google-trends-mcp)

HTML

<a href="/listings/john-of--google-trends-mcp"><img src="/api/listings/john-of--google-trends-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.11+ (developed on 3.12).

git clone https://github.com/John-OF/google-trends-mcp.git
cd google-trends-mcp
python -m venv .venv

Install the dependencies with the virtual environment's Python:

# Windows
.venv\Scripts\python.exe -m pip install -r requirements.txt
# macOS / Linux
.venv/bin/python -m pip install -r requirements.txt

Check that it starts (it waits on stdio; press `Ctrl+C` to exit):

.venv/bin/python server.py          # Windows: .venv\Scripts\python.exe server.py

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines
  1. # Google Trends MCP
  2. [![CI](https://github.com/John-OF/google-trends-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/John-OF/google-trends-mcp/actions/workflows/ci.yml)
  3. ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  5. An MCP server (FastMCP, stdio) that turns Google Trends into an editorial
  6. research tool for AI agents: find out what a country started searching for in
  7. the last few hours, check whether a keyword has real and sustained demand, and
  8. collect the source articles behind a trend, all before writing a single word.
  9. Built for a daily blogging workflow (pick a topic → validate demand → gather
  10. sources → hand them to a writing/publishing tool), but the tools are generic.
  11. <p align="center">
  12. <img src="assets/demo.svg" width="800" alt="An agent calls get_daily_trends, get_search_metrics and get_trend_articles, picks the trend with the best opportunity score and collects three direct source URLs">
  13. </p>
  14. <p align="center"><sub>Real data from a run on 2026-11-20 (US). Regenerate with <code>python tools/make_demo.py</code>.</sub></p>
  15. Google has **no official Trends API**. This server uses two public paths:
  16. | Tool | Source | Returns |
  17. |---|---|---|
  18. | `get_daily_trends` | "Trending now" RSS feed | The ~10 trends that most recently took off in a country, with approximate search volume |
  19. | `get_trend_articles` | Same feed | The articles from the **"In the news"** panel of a trend, with direct publisher URLs |
  20. | `get_search_metrics` | [`pytrends`](https://github.com/GeneralMills/pytrends) (Interest Over Time + Related Queries) | Derived per-keyword metrics: momentum, seasonality, opportunity score |
  21. > **Why only the RSS feed?** Until November 2026 the first two tools used the
  22. > internal API behind [trends.google.com/trending](https://trends.google.com/trending)
  23. > (`batchexecute`), which exposed the full 4 h / 24 h / 48 h / 7 d windows
  24. > (hundreds of trends), growth percentages and the trend breakdown. Google then
  25. > put that endpoint behind a reCAPTCHA Enterprise token: without it, every
  26. > request returns `PERMISSION_DENIED`. Getting around a CAPTCHA is not something
  27. > this project does, so it now relies only on the public feed, which still
  28. > carries volumes and direct article links.
  29. ---
  30. ## Installation
  31. Requires Python 3.11+ (developed on 3.12).
  32. ```bash
  33. git clone https://github.com/John-OF/google-trends-mcp.git
  34. cd google-trends-mcp
  35. python -m venv .venv
  36. ```
  37. Install the dependencies with the virtual environment's Python:
  38. ```powershell
  39. # Windows
  40. .venv\Scripts\python.exe -m pip install -r requirements.txt
  41. ```
  42. ```bash
  43. # macOS / Linux
  44. .venv/bin/python -m pip install -r requirements.txt
  45. ```
  46. Check that it starts (it waits on stdio; press `Ctrl+C` to exit):
  47. ```bash
  48. .venv/bin/python server.py # Windows: .venv\Scripts\python.exe server.py
  49. ```
  50. ---
  51. ## Registering the server in your MCP client
  52. Always point to the **virtual environment's** Python, not the system one. In the
  53. examples below, replace `<path-to-repo>` with the absolute path where you cloned
  54. the repository (on macOS/Linux, use `.venv/bin/python` instead of
  55. `.venv/Scripts/python.exe`).
  56. **Claude Code, user scope** (available in every project):
  57. ```bash
  58. claude mcp add g-trends --scope user -- "<path-to-repo>/.venv/Scripts/python.exe" "<path-to-repo>/server.py"
  59. ```
  60. **Claude Code, project scope:** copy `.mcp.json.example` to `.mcp.json` and fill
  61. in the paths. It is loaded automatically when Claude Code opens the folder.
  62. **Claude Desktop** (`claude_desktop_config.json`):
  63. ```json
  64. {
  65. "mcpServers": {
  66. "g-trends": {
  67. "command": "<path-to-repo>/.venv/Scripts/python.exe",
  68. "args": ["<path-to-repo>/server.py"]
  69. }
  70. }
  71. }
  72. ```
  73. ---
  74. ## Tools
  75. ### 1. `get_daily_trends(geo, limit, sort, include_news)`
  76. The trends that most recently took off in a country, newest first.
  77. | Parameter | Type | Default | Description |
  78. |---|---|---|---|
  79. | `geo` | str | `"US"` | ISO alpha-2 code: `US`, `GB`, `CA`, `AU`, `IE`, `NZ`… |
  80. | `limit` | int (1-25) | `10` | Number of trends returned after sorting (the feed holds ~10) |
  81. | `sort` | `recency` \| `volume` | `recency` | `recency` keeps the feed order (newest first) |
  82. | `include_news` | bool | `false` | Attach each trend's articles inline (no extra requests) |
  83. ```json
  84. {
  85. "ok": true,
  86. "geo": "US",
  87. "sort": "volume",
  88. "source": "rss",
  89. "fetched_at": "2026-11-20T05:02:11+00:00",
  90. "total_available": 10,
  91. "count": 3,
  92. "trends": [
  93. {
  94. "rank": 7,
  95. "title": "toyota recalls",
  96. "volume": 20000,
  97. "volume_label": "20000+",
  98. "started": "2026-11-20T04:30:00+00:00",
  99. "explore_url": "https://trends.google.com/trends/explore?q=toyota+recalls&geo=US&date=now%207-d",
  100. "picture": "https://encrypted-tbn0.gstatic.com/images?q=...",
  101. "picture_source": "Fox Business",
  102. "news_available": true
  103. }
  104. ]
  105. }
  106. ```
  107. `volume` is Google's absolute approximation (`20000+` → 20000), **not** the
  108. relative 0-100 index returned by `get_search_metrics`. `rank` is the position in
  109. the feed, which is ordered by start time.
  110. ### 2. `get_trend_articles(trend, geo, limit)`
  111. The articles behind one specific trend: the **"In the news"** panel the website
  112. shows when you click a trend. These are the URLs you hand to a writing tool as
  113. source material.
  114. | Parameter | Type | Default | Description |
  115. |---|---|---|---|
  116. | `trend` | str | — | Trend title; partial, case-insensitive matches work |
  117. | `geo` | str | `"US"` | The same country you found it in |
  118. | `limit` | int (1-10) | `10` | Maximum number of articles (the feed carries about 3 per trend) |
  119. ```json
  120. {
  121. "ok": true,
  122. "geo": "US",
  123. "trend": "toyota recalls",
  124. "matched_by": "exact",
  125. "volume_label": "20000+",
  126. "article_count": 3,
  127. "articles": [
  128. {
  129. "title": "Over 314K older Toyota, Lexus vehicles recalled ...",
  130. "source": "Fox Business",
  131. "url": "https://www.foxbusiness.com/lifestyle/over-314k-older-toyota-lexus-vehicles-recalled-potentially-dangerous-airbag-issue",
  132. "snippet": null,
  133. "image": "https://encrypted-tbn0.gstatic.com/images?q=..."
  134. }
  135. ],
  136. "urls": ["https://www.foxbusiness.com/lifestyle/over-314k-older-toyota-lexus-vehicles-recalled-potentially-dangerous-airbag-issue", "..."]
  137. }
  138. ```
  139. `urls` is a flat list of links, ready to pass as-is to another tool. **They are
  140. direct publisher URLs** (`foxbusiness.com`, `usatoday.com`, `billboard.com`),
  141. not Google redirects, so they can be opened and read.
  142. If the trend has already rotated out of the feed, the tool returns `ok: false`
  143. along with `available_trends` (the current titles).
  144. ### 3. `get_search_metrics(keywords, geo, timeframe, include_related)`
  145. Demand metrics for up to 5 keywords, compared against each other.
  146. | Parameter | Type | Default | Description |
  147. |---|---|---|---|
  148. | `keywords` | list[str] (1-5) | — | Google's hard limit: 5 per request |
  149. | `geo` | str | `"US"` | ISO alpha-2, or `""` for worldwide |
  150. | `timeframe` | str | `"today 12-m"` | `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all`, or `YYYY-MM-DD YYYY-MM-DD` |
  151. | `include_related` | bool | `true` | Adds `top` and `rising` related queries (ideas for angles) |
  152. Metrics computed per keyword:
  153. | Field | Meaning |
  154. |---|---|
  155. | `average_interest` / `peak_interest` / `latest_interest` | Relative 0-100 index |
  156. | `peak_date` | Date of the peak |
  157. | `momentum_pct` | Last 4 points vs. the previous 4 (with weekly data ≈ month over month) |
  158. | `slope_pct_per_period` | Least-squares slope, normalised to the average |
  159. | `volatility_pct` | Coefficient of variation (one-off spikes vs. steady demand) |
  160. | `trend` | `rising` / `stable` / `declining` |
  161. | `is_breakout` | At its highs (≥90) and rising sharply (≥50 %) |
  162. | `seasonality` | Average per month, best/worst month and the current month's `season_fit_pct` |
  163. | `opportunity_score` | `0.40·average + 0.35·(50+momentum) + 0.25·season_fit`, each term clamped to 0-100 |
  164. Plus a `ranking` already sorted by `opportunity_score`, and the `resolution`
  165. (hourly/daily/weekly/monthly) of the series Google returned.
  166. **The 0-100 values are relative to the keywords in that same call.** To compare
  167. candidates, send them together in a single call; never compare numbers across
  168. separate calls.
  169. ---
  170. ## Suggested workflow
  171. 1. `get_daily_trends(geo="US")` → the topics that just started trending. The
  172. feed rotates every few minutes, so checking a few times a day (or across
  173. several countries) widens the pool.
  174. 2. Filter the ones that fit your niche.
  175. 3. `get_search_metrics(keywords=[3-5 candidates], geo="US", timeframe="today 12-m")`
  176. → keep the highest `opportunity_score`; check `season_fit_pct` so you don't
  177. write about a topic in its worst month.
  178. 4. `get_trend_articles(trend="<the chosen one>")` → take `urls` and pass them to
  179. your writing/publishing tool (e.g. a WordPress MCP) as sources.
  180. 5. Use `related_queries.rising` for subheadings and long-tail keywords.
  181. Example prompt:
  182. > Get the current trends in the US, keep the travel-related ones, measure the top 5
  183. > with `get_search_metrics` over 12 months, and for the one with the highest
  184. > `opportunity_score` fetch its articles with `get_trend_articles`. Then write
  185. > the post using those URLs as sources and the rising queries as H2s.
  186. ---
  187. ## Limits and caveats
  188. - **Rate limiting (429):** `get_search_metrics` hits unofficial endpoints. The
  189. server retries with exponential backoff (3 attempts) and, if it still fails,
  190. returns `{"ok": false, "rate_limited": true}` instead of crashing. Space your
  191. calls out: a few per session, not dozens in a row.
  192. - **`pytrends` is no longer maintained.** `get_search_metrics` depends on it, so
  193. if Google changes the endpoints it relies on, that tool will stop working and
  194. no upstream fix will come. The other two tools do not use `pytrends`.
  195. - **The feed is small and has no filters.** It holds only the ~10 most recent
  196. trends per country, with no time window, category filter, growth percentage
  197. or trend breakdown; those now live behind the website's reCAPTCHA (see above).
  198. Filter the topics yourself.
  199. - **Trends rotate.** Call `get_trend_articles` soon after `get_daily_trends`,
  200. or the topic may have left the feed.
  201. - **Google News deliberately left out:** `news.google.com/rss/search` returns
  202. ~100 articles per term, but its links are `news.google.com/rss/articles/CBM...`
  203. redirects that do not resolve server-side (the hop happens in JavaScript).
  204. They would be useless to a writing tool. The "In the news" panel links do go
  205. straight to the publisher.
  206. - **Encoding:** the XML is parsed from bytes, not from `response.text`;
  207. otherwise typographic quotes in headlines arrive corrupted and leak into the
  208. final article.
  209. - **Partial points:** the last, still-incomplete period is dropped before
  210. computing metrics (otherwise it artificially drags `momentum_pct` down). It is
  211. reported in `partial_points_dropped`.
  212. - **pytrends + urllib3 2.x:** pytrends 4.9.2's built-in retry is broken
  213. (`method_whitelist` was removed in urllib3 2.0). That is why retrying is
  214. implemented in `server.py` (`_retry`) and no `retries`/`backoff_factor` is
  215. passed to `TrendReq`.
  216. - **FastMCP:** pinned to `<3.0`, following the project's own recommendation.
  217. ---
  218. ## Development
  219. ```bash
  220. python -m pip install -r requirements-dev.txt
  221. python -m pytest # offline: every network call is mocked
  222. python -m ruff check .
  223. ```
  224. The tests never hit Google: HTTP is replaced with `httpx.MockTransport` and the
  225. fetchers are monkeypatched, so the suite runs in about a second. CI runs lint
  226. and tests on Python 3.11, 3.12 and 3.13.
  227. ---
  228. ## Disclaimer
  229. This project is not affiliated with, endorsed by or sponsored by Google. It
  230. relies on undocumented endpoints that may change or stop working at any time.
  231. Use it responsibly and within Google's terms of service.
  232. ## License
  233. [MIT](LICENSE) © 2026 John Orellana

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.