<p align="center"><img src="assets/banner.svg" alt="Google Trends MCP Server — works with Claude, ChatGPT Codex, Cursor, VS Code and Windsurf" width="100%"></p>

Google Trends MCP Server — gtrends-mcp-full

The complete MCP server for Google Trends. Ask Claude, Cursor, Windsurf, VS Code, Codex or any other MCP client what people are searching, where, when, and what is taking off right now — and get analysis back, not a chart to squint at.

32 tools · Trending Now with real search volumes · interest over time, by region and related searches · seasonality, momentum and share of search · no API key, no browser, no sign-in.

Project page · Quick start · Tools · Prompts · Configuration · How it stays unblocked · FAQ · Docs

---

<p align="center"><img src="assets/demo.gif" alt="Claude answering whether heat pump searches are growing in the UK, using the trend_momentum and seasonality tools of gtrends-mcp-full" width="100%"></p>

What you get

| | | |---|---| | ✅ Complete | Everything the Google Trends website shows: the full Trending Now list (hundreds of trends per country, with search volume, growth, start time, category and the queries inside each one), the news behind a trend, interest over time down to the minute, interest by country, region, city and metro area, related queries and topics, every category and location, Web, YouTube, News, Images and Shopping search. | | 🔑 Nothing to set up | No API key, no Google Cloud project, no sign-in, no headless browser. Install it and ask. | | 🧠 Answers, not charts | Is it growing or fading? When does it peak, and when must the content be live? Who is winning share of search? What suddenly jumped, and when? Worked out for you and returned as short tables your AI can reason about. | | 📈 Past the limits of the website | Compare 25 terms on one scale instead of five. Daily data over years instead of nine months. Trending Now history kept for as long as you like instead of one week. | | 🛡️ Built to keep working | Paced requests, a persistent session, back-off instead of hammering, and a cache that still answers — and says so — when Google will not. Related-searches and chart requests are budgeted separately, so a limit on one never takes down the rest. | | 🎯 Honest numbers | Every value is labelled for what it is: Google's 0–100 index, never a search count. Partial periods are marked. A failure is an error with its reason and what to do next, never an empty result. | | 💸 Free and light | MIT licensed. Two dependencies. Runs on your machine; nothing is sent anywhere but Google. Tested on Linux, macOS and Windows with Python 3.10–3.13. |

Works with: Claude Desktop · Claude Code · Cursor · Windsurf · VS Code (Copilot agent mode) · OpenAI Codex CLI · any MCP client over stdio or HTTP.

Tools

32 tools in 5 groups. You don't call them yourself — ask in plain language and your AI picks the right one.

🗄️ works on the local data file, no request to Google

🔥 Trending now

| Tool | What it gives you | Ask it like this | |---|---|---| | trending_now | The full Trending Now list for a country or region: search volume, growth, start time, still active or over, category, and the other queries people type for the same story. Filter by category, status, volume or text | "What's trending in Germany in the last 4 hours?" · "Active sports trends in the US above 100K searches" | | trend_details | One trend in full: every query inside it, the news articles behind it, and its hour-by-hour curve for the past week | "Why is 'pentobarbital' trending?" | | trending_feed | The top daily trends with headlines and links — the fastest answer to "what's in the news there today" | "Give me today's top searches in Iran with the headlines" | | trending_across_countries | Trends that are live in several countries at once, grouped even when titles differ | "What is trending in both the US and the UK right now?" | | match_trends | Which current trends touch your subjects, brands or products — for newsjacking | "Is anything about electric cars, Tesla or charging trending today?" |

🔎 Explore a keyword

| Tool | What it gives you | Ask it like this | |---|---|---| | keyword_overview | The whole Trends page in one call: curve, direction, top places, rising and top related queries | "Give me the Google Trends picture for 'heat pump' in the UK" | | interest_over_time | The main chart for up to 5 terms on one scale — any range from one hour to 2004-today, any location, category and search type, with operators (a + b, a -b, "a b") | "Compare tesla and byd over 5 years in Germany" · "YouTube interest in 'lofi' this week" | | interest_by_region | Where a term matters most: countries, regions, cities or metro areas. With several terms: who leads where | "Which US states search 'tesla' the most?" · "Where does byd beat tesla?" | | related_queries | What else people search around a term — the top queries and the rising ones, with breakouts flagged | "What are the rising searches around 'solar panels'?" | | related_topics | The people, brands and things searched alongside a term, with topic ids | "Which topics are related to 'tesla'?" | | compare_periods | One term in two time ranges on one scale: this year against last, this quarter against the one before | "Is 'sunscreen' ahead of last summer?" | | compare_locations | One term in up to 5 countries or regions side by side | "Compare interest in cricket in India, the UK and Australia" |

🧠 Analysis

| Tool | What it gives you | Ask it like this | |---|---|---| | trend_momentum | A verdict per term — breakout, rising, stable, declining or new — with year-over-year change, last quarter vs the one before, long-run slope and distance from its peak | "Which of these eight product ideas is actually growing?" | | seasonality | The yearly rhythm: a month-by-month index, peak and low months, how reliably it repeats, year-by-year growth, the next six months, and the date content should be live | "When do people search for air conditioners, and when should I publish?" | | content_calendar | A publishing calendar for up to 8 topics, sorted by what is due first; evergreen topics listed separately | "Build me a content calendar for these topics" | | share_of_search | Your brand's share of searches against up to 4 competitors — overall, at the start, at the end, and the change in points | "What's Toyota's share of search against Honda, Ford and Tesla?" | | compare_many | 6 to 25 terms ranked on a single scale, past the five-term limit of the website | "Rank these 20 car brands by search interest in the US" | | find_spikes | The moments a term jumped: when each spike began, peaked and ended, and how many times the usual level it reached | "When did searches for 'earthquake' spike in the last five years?" | | daily_history | Day-by-day interest over years (the website stops at about nine months), plus the weekday pattern | "Daily interest in 'pizza delivery' for 2024 and 2025 — which weekday is biggest?" | | keyword_ideas | Rising and top related queries for up to 5 seeds, merged and de-duplicated, breakouts first | "Give me keyword ideas around 'electric bike' and 'e-scooter'" |

🗄️ History that Google does not keep

| Tool | What it gives you | Ask it like this | |---|---|---| | snapshot_trending | Saves the current Trending Now list to a local file. Google drops a trend after about a week; this keeps it | "Save today's trends for the US, UK and Germany" | | trending_history 🗄️ | Searches everything saved: when something trended, how big it got, how long it lasted | "Did anything about 'iphone' trend in the US last month?" | | watchlist_add 🗄️ | Puts terms on a watchlist, per location, with a note | "Watch 'heat pump' and 'solar panels' in the UK" | | watchlist_report | The watchlist measured now: direction, what changed since the last report, and whether a term is trending today | "How is my watchlist doing?" | | watchlist_remove 🗄️ | Takes terms off the watchlist | "Stop watching 'fax machine'" | | history_sql 🗄️ | Read-only SQL over the saved trends, snapshots, watchlist and readings | "Which categories trended most in Germany this month?" |

🧭 Lookups and utilities

| Tool | What it gives you | Ask it like this | |---|---|---| | find_location | The code for any country, region, state or metro area, or the list of places inside one | "What's the Google Trends code for Tehran province?" | | find_category | Category ids, to pin an ambiguous word to one meaning | "Limit 'jaguar' to cars" | | find_topic | Google's topics for a name — one id that covers every language and spelling of a thing | "Use the company Tesla, not the word" | | get_capabilities 🗄️ | Settings, session state, cache and history coverage, the tool list | "Is the Trends server set up correctly?" | | check_endpoints | Asks each Google Trends endpoint one question and reports which still answer | "Why did the last Trends call fail?" | | clear_cache 🗄️ | Drops saved answers, optionally resets the session | "Refresh the trending data" |

The full reference with every parameter is in docs/tools.md — generated from the code, so it is never out of date.

Prompts

Four ready-made workflows that appear in your client's prompt menu. Each chains several tools and says what the finished answer must contain.

| Prompt | What it produces | |---|---| | trend_report | A full read on one keyword: direction, seasonality, the events behind its spikes, rising themes, and what to do about it | | newsjacking_brief | Today's trends that fit your subjects, the story behind each, the queries to target, an angle and a risk note | | seasonal_content_plan | A twelve-month publishing plan for a list of topics | | market_comparison | Share of search for a brand against its competitors, who wins where, and what is rising around each |

Two reference pages are also exposed as MCP resources: gtrends://guide (how to read the numbers, time ranges, operators, topics) and gtrends://trending-categories.

Quick start

You need Python 3.10 or newer and uv (or pip).

1. Add it to your client

Nothing to download first: uvx fetches the package from PyPI and runs it.

Claude Code

claude mcp add gtrends -- uvx gtrends-mcp-full

Claude Desktop, Cursor, Windsurf, VS Code — add this to the client's MCP configuration:

{
  "mcpServers": {
    "gtrends": {
      "command": "uvx",
      "args": ["gtrends-mcp-full"],
      "env": {
        "GTRENDS_GEO": "US",
        "GTRENDS_TIMEZONE": "America/New_York"
      }
    }
  }
}

Both env entries are optional. There is nothing else to configure: no key, no sign-in.

2. Check it

uvx gtrends-mcp-full doctor

doctor asks every Google Trends endpoint one question; all eight should say OK. On the very first run a chart endpoint may report that the session is still being validated — that passes after a minute and a half and does not come