google-trends-mcp

# Google Trends MCP Server

<!-- mcp-name: com.hasdata/google-trends -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client one Google Trends tool. Pull interest over time, interest by region, and the rising and top related queries and topics for any term, all as structured JSON, with no scraping library to keep alive and no Google account.

```
https://mcp.hasdata.com/api/mcp?apis=google_trends
```

[![Glama score](https://glama.ai/mcp/servers/HasData/google-trends-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/google-trends-mcp)
[![tool contract](https://github.com/HasData/google-trends-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/google-trends-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-1-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=google-trends-mcp), free to create with no card, and the trial covers about 200 calls at the 5-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run and no Google account anywhere in the flow. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/google-trends-mcp` on npm and `hasdata-google-trends-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=google_trends` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http google-trends "https://mcp.hasdata.com/api/mcp?apis=google_trends" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=google_trends` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/google-trends-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-trends-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "uvx",
      "args": ["hasdata-google-trends-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "google-trends": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "google-trends": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "google-trends": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent picks the tool itself. Each is annotated with the calls it takes, because every successful call costs 5 credits.

> Chart interest in "cold brew coffee" in the US over the past 12 months and tell me which weeks it peaked.

*One call, 5 credits. The weekly series comes back in a single request.*

> For "cold brew coffee" in the US, give me the rising related queries and flag the ones marked Breakout.

*One call, 5 credits.*

> Compare interest in "cold brew" against "iced coffee" worldwide over five years and say which one is growing.

*One call, 5 credits. The tool takes several terms in one timeseries request.*

> Show me interest in "sunscreen" by US state over the past 90 days so I can see where demand is highest.

*One call, 5 credits. This is the interest-by-region view at state granularity.*

A comparison across terms rides in one `timeseries` call. Region breakdowns, related queries and related topics are each their own `dataType`, so a prompt that wants a chart plus its rising queries is two calls.

## Tools

One tool, read-only. The sample below is trimmed from a real call, and the numbers move as the trend moves. Read it as a shape. The tool name links to its endpoint reference, which carries the full parameter list.

The sample is the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Get Google Trends data

[`hasdata_google_trends_search_getTrendsData`](https://docs.hasdata.com/apis/google-trends/search?utm_source=github&utm_medium=syndication&utm_campaign=google-trends-mcp)

Interest over time, by region, or the related queries and topics for a term.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `q` | string | yes | The search term. `timeseries` and `geoMap` take up to 5 comma-separated terms to compare, and a sixth is rejected with a 400 |
| `dataType` | string | | `timeseries` by default, plus `geoMap`, `relatedTopics` and `relatedQueries`. The two related types take a single term only |
| `date` | string | | A window such as `now 7-d`, `today 12-m`, `today 5-y` or `all`, or a custom `yyyy-mm-dd yyyy-mm-dd` range |
| `geo` | string | | A location code such as `US` or `US-CA`. Worldwide when empty |
| `region` | string | | Granularity for `geoMap` only: `country`, `region` (subregion), `dma` (metro) or `city`. The default depends on `geo`, `country` worldwide and finer once a `geo` is set |
| `cat` | string | | Category id to narrow the term. `0` is all categories |
| `gprop` | string | | The Google property: `images`, `news`, `froogle` (Shopping) or `youtube`. Web search when empty |
| `tz` | number | | Time-zone offset in minutes, default `420` (PDT). Shifts how hourly ranges are bucketed |

The response key depends on `dataType`. `timeseries` returns `interestOverTime.timelineData`, `geoMap` returns interest by region, and the related types return `relatedQueries` or `relatedTopics`, each split into `rising` and `top`. Read the key that matches the type you asked for.

`timeseries` (the default) returns a value from 0 to 100 for each point, both as a string and pre-parsed in `extractedValue`. The most recent point often carries `isPartial: true`, meaning the week is still filling in. Drop it before you compute a trend, or the last bar reads as a dip that is not real.

```json
{
  "interestOverTime": {
    "timelineData": [
      { "date": "Apr 12 – 18, 2026", "timestamp": "1775952000", "isPartial": false,
        "values": [{ "query": "cold brew coffee", "value": "100", "extractedValue": 100, "hasData": true }] },
      { "date": "Aug 23 – 29, 2026", "timestamp": "1787443200", "isPartial": true,
        "values": [{ "query": "cold brew coffee", "value": "44", "extractedValue": 44, "hasData": true }] }
    ]
  }
}
```

`relatedQueries` splits into `rising` and `top`. A rising entry reads as a percentage like `+300%`, or `Breakout` for a jump too large to score, and `extractedValue` gives the number behind it. A `Breakout` comes back with a sentinel `extractedValue` well above any real percentage, so sort on the string label, not on the raw number.

```json
{
  "relatedQueries": {
    "rising": [
      { "query": "organic cold brew coffee", "value": "+300%", "extractedValue": 300, "link": "https://trends.google.com/trends/explore?q=organic+cold+brew+coffee&date=today+12-m&geo=US" }
    ],
    "top": [
      { "query": "how to cold brew coffee", "value": "100", "extractedValue": 100, "link": "https://trends.google.com/trends/explore?q=how+to+cold+brew+coffee&date=today+12-m&geo=US" }
    ]
  }
}
```

The [endpoint reference](https://docs.hasdata.com/apis/google-trends/search?utm_source=github&utm_medium=syndication&utm_campaign=google-trends-mcp) lists every `geo`, `cat` and date format the tool accepts.

## Errors and failure paths

Your client almost never sees an HTTP error code from a tool call. The MCP layer answ