Skip to main content
Glama
WARNING

Unofficial. Not affiliated with or endorsed by Google. This project calls undocumented public Google Trends web endpoints that can change or fail without notice, and use may conflict with Google's Terms of Service. Use it for light, interactive analysis, not bulk scraping or an SLA.

google-trends-for-agent gives agents and humans a predictable way to ask how search interest is changing: a stable JSON envelope, calibrated searches/day estimates, charts, and explicit error codes instead of invented numbers.

Choose a route

Muse, GrokBot and Dots: use Apify on demand by default, with either the public Actor or your own deployment. Use the managed remote MCP gateway where supported, or the client's authenticated Apify connector/API. See the client setup guide. Local access remains available for development and explicit direct-use setups.

Route

Where it runs

Execution

Public Actor

Your Apify account

One run per query; exits when done, no deployment

My own Actor

Your Apify account

Deploy once, then run on demand

Local

This machine

CLI, stdio MCP, or native dsh tools

Deploy it yourself

Fork the repository and build it with Link Git repository in Apify Console, or run apify push. Keep Server / Standby disabled. In dsh, select My own Actor, sign in with Apify, and select the built Actor.

For an existing deployment from official main, use Update selected Actor in dsh. After the build finishes, Test connection shows keyword access and the actual Actor/plugin versions separately. Custom or pinned source is updated in Apify Console. See the release and acceptance checklist.

Remote MCP

For Muse, GrokBot and Dots with remote MCP support, use Apify's hosted gateway and complete OAuth in the client:

{
  "mcpServers": {
    "google-trends": {
      "url": "https://mcp.apify.com?tools=meka.im/google-trends-for-agent"
    }
  }
}

For your own deployment, replace meka.im/google-trends-for-agent in tools= with your account's <username>/<actor-name>. The account must have access to it.

The gateway exposes this project as an Actor tool and supplies Dataset, key-value-store, and abort tools. It starts a one-off run; it does not promise the four direct trends_* names. Local MCP and the native dsh plugin provide the four trends_* tools. For ordinary tool / terms Actor input, read the results using the returned Dataset id.

Apify's full_api_access OAuth scope grants account-wide API access. Clients without MCP OAuth can configure a Bearer header through their credential storage. See the Actor reference and Actor costs.

Related MCP server: Google Trends MCP

Install & quick start

The CLI/MCP require Node.js 20+. Nothing is published to npm; npx builds the package from the GitHub checkout on first run. The commands below follow the repository's main branch.

npx -y -p github:meka-im/google-trends-for-agent gtfa snapshot Sora --geo US --json --pretty

Building the GitHub dependency was verified with npm 11.19.1. npm 10.9.4 can build it and then fail while packaging it with a GitFetcher error about a missing Arborist dependency. If you hit that error, use the clone → npm ci → pack flow below or upgrade npm. The CLI and installed package still require Node.js 20+.

The zero-install npx path builds from git on first use; build time depends on the network and machine. For frequent use, prefer a persistent install or the MCP server.

Persistent install (clone first because npm global git installs can omit build devDependencies during prepare). Pack and install the tarball so the clone can be deleted afterwards:

git clone https://github.com/meka-im/google-trends-for-agent.git
cd google-trends-for-agent
npm ci
npm install -g "$(npm pack | tail -1)"

The clone tracks the repository's default main branch. If your review process requires an immutable source revision, add your own commit pin rather than relying on a moving branch.

The packed tarball bundles the audited apify dependency tree so a consumer install does not re-resolve older vulnerable Apify transitives. Root npm overrides do not propagate into consumers, so this bundle is part of the consumer protection. The root also applies an explicit @crawlee/core → minimatch ^11.0.1 security override (lock: 11.0.8); Crawlee declares ^9, so consumer npm ls may show a range warning even though the explicit override is intentional. Audits cover both the root tree and a clean install of the packed artifact. Bundling materially increases package size.

The CLI is gtfa; gtfa-mcp runs the local MCP server. Both default to local egress (this machine's network) and also support Apify on-demand cloud egress (--egress actor-public or --egress actor-own --actor <id>, or GTFA_EGRESS / GTFA_APIFY_ACTOR with APIFY_TOKEN), giving direct access to the four trends_* tools through Apify's residential proxy. For managed remote MCP without a local Node process, Muse, GrokBot and Dots should start with the Apify setup:

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["-y", "-p", "github:meka-im/google-trends-for-agent", "gtfa-mcp"]
    }
  }
}

To route local stdio MCP or CLI calls through Apify's public Actor with APIFY_TOKEN in the client's secure environment:

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["-y", "-p", "github:meka-im/google-trends-for-agent", "gtfa-mcp", "--egress", "actor-public"],
      "env": { "APIFY_TOKEN": "<your-apify-token>" }
    }
  }
}

After the persistent install, use this config (or an absolute path to gtfa-mcp) to avoid resolving the GitHub package through npx on every start:

{
  "mcpServers": { "google-trends": { "command": "gtfa-mcp", "args": [] } }
}

For a local Streamable HTTP endpoint (bound to 127.0.0.1):

npx -y -p github:meka-im/google-trends-for-agent gtfa-mcp --http --port 4321   # http://127.0.0.1:4321/mcp

Check both package-download and data-fetch connectivity:

curl -I https://github.com
curl -I https://trends.google.com

If npx … exits 128 with empty stdout/stderr, the GitHub package fetch failed before gtfa started; inspect the npm debug log (typically ~/.npm/_logs/). MCP fails to start means npx/git errors or EOF before the handshake. MCP started but a tool fetch failed means the handshake and tools/list succeed, but the tool returns NETWORK_ERROR, RATE_LIMITED, or another upstream error. Use gtfa doctor --json for the latter.

dsh plugin

Prerequisites: dsh requires Node >=24.9 and pnpm >=10 on PATH (allowBuilds needs pnpm 10; tested with 10.34.6). Install dsh with npm i -g @deepseek-ai/dsh and pnpm with npm i -g pnpm@10. The gtfa CLI/MCP alone require Node 20+ (engines.node: >=20). Without pnpm on PATH, plugin installation fails with spawn pnpm ENOENT / pnpm was not found.

dsh plugin --profile web add github:meka-im/google-trends-for-agent

After installing or upgrading the plugin, fully quit and reopen dsh to load its backend. Saving plugin settings applies them immediately.

The first run usually prints a key and fails; a cached build in the pnpm store may pass immediately. Append the block below, using the exact key pnpm prints (ending in the commit hash), to the YAML dsh already generated at $DSH_HOME/profiles/web/pnpm-workspace.yaml (DSH_HOME defaults to ~/.dsh). Keep all existing keys; do not overwrite the file. Then re-run the command. For another profile, replace web in both the command and the path:

allowBuilds:
  "google-trends-for-agent@https://codeload.github.com/meka-im/google-trends-for-agent/tar.gz/<commit>": true

pnpm's box may wrap the key across lines — copy it from this template, only the commit hash changes.

pnpm suggests an onlyBuiltDependencies: list; dsh profiles require an allowBuilds: map with : true (a list under allowBuilds fails). The key changes whenever main moves; re-add it after updates.

The plugin is enabled by default after install and provides four native tools plus a gtfa skill. In dsh 0.2.2-rc.1, open dsh web → Plugins → Google Trends (the installed-plugin card), then under Components click the Google Trends / gtfa row to open the settings page. Choose Local (this machine), Public Actor, or My own Actor under Egress, then click Save; login itself needs no Save. When the Host provides its credentials service, both Actor routes offer Sign in with Apify: the page shows Apify's official authorization link and user code, checks pending status every 2 seconds while honoring Apify's polling interval (including slow_down), pauses when closed, resumes when reopened, and restarts an expired attempt. Apify's only current device OAuth scope is full_api_access—full Apify API access, not access limited to this Actor or tool.

The settings page uses three egress cards, with OAuth status and usage directly below. Expand Usage details for billing-cycle and proxy details. Advanced groups Calibration baselines, Manual Token (Actor routes only), and Files and charts. Save and Discard float above the page while scrolling; Test connection checks the current connection, including unsaved Actor or manual-token changes, without saving them. Use the account menu beside the connection check to sign out. The layout follows the Host's light/dark theme and stacks on narrow screens.

Credentials are re-resolved on every operation: a stored OAuth session is used first; only when none is stored does the plugin use the saved config token, then APIFY_TOKEN. A stored session that is expired or damaged and cannot be refreshed requires signing in again; it does not silently fall back or report success. OAuth credentials do not enter browser-visible status or model-visible tool input/output; Host-internal code resolves them through the credentials service. Without that service, OAuth is unavailable, while local egress, the manual token, and APIFY_TOKEN still work. For the dsh device flow, the current access token is long-lived with no refresh token; future standard expiry/refresh responses can be handled by the plugin.

Persistence is delegated to the dsh credentials service/provider-managed store, separate from the profile; backend location, record keys, and schema can vary. The current local file-backed provider uses owner-only 0700 directory and 0600 file permissions when applicable; it is not an OS Keychain or encrypted storage and cannot stop other processes under the same OS user from reading it. The manual token remains an Advanced / fallback option and is still stored in plaintext in cordis.patch.yml (mode 0600), hidden in the UI, never logged, and absent from browser-visible status and model-visible tool input/output. Cancel only stops a pending flow. Sign out removes the stored OAuth session but retains reusable client registration according to the provider backend; it does not revoke the cloud authorization, so use Apify Console for that. See the dsh plugin reference for routes and lifecycle details.

Open Google Trends from the dsh sidebar (or More) for Query and History. Single-term snapshots and comparisons default to 7 days (now 7-d) and support all nine time ranges, from the past hour to all time. Plugin settings opens the existing installed-plugin page. Chat still uses the same four native tools.

The query form accepts 1–5 comma-separated keywords and selects the tool automatically. Multi-term queries use one shared batch and one on-demand Actor run, with a calibration anchor included when space permits. The current adapter uses Classic Explore's five comparison slots; Google's new Explore interface supports more groups. Five selected terms occupy this adapter's whole batch; volume can then be calibrated only if one of them is already a known regional anchor. Missing or weak calibration stays null. The page shows real Actor stages and elapsed time, and retains the draft, in-flight request and result when navigating to another dsh panel. Cancel explicitly stops the current request; closing/reloading the browser or unloading the plugin cancels it.

The Host retains the latest 1,000 manual and Agent calls under <snapshotDir>/.query-history, including failures and saved result copies. Viewing or refreshing history never starts a query. Clear individual, selected, or all records with confirmation; statistics follow retained records, while query caches, Apify runs and billing remain separate. Actor costs show only amounts returned by linked runs; missing amounts stay unknown. Opening the dashboard starts no Actor and performs no background data collection.

Relative snapshotDir and chartDir paths resolve from the directory where dsh web was started (cwd); charts default to <cwd>/.gtfa/charts/.

Test connection verifies connectivity and real data for ChatGPT, Gemini and weather together (US, past 24 hours). It shows each keyword's data-point counts and supports cancellation. Actor mode starts one usage-billed run after preflight, then exits; the check stops on challenges or rate limits without retrying.

MCP tools

Tool

What it does

trends_ask

Interest, Popular/Rising queries, regions, optional verdict and diff (default: US, now 7-d).

trends_snapshot

Calibrated searches/day with multi-tier MEKA auto-calibration (automatic 2nd-round tier retry when out of range), anchor/traffic/calibration blocks, verdict, chart7d / traffic7d.

trends_compare

Relative 0–100 interest for 1–5 distinct keywords on one shared scale; optional calibrate: true attaches multi-tier batchVolume estimates.

trends_now

Trending Now by country, with rank, growth, categories, and links.

Inputs, time windows, defaults, and envelope fields are in the reference and the MCP field guide.

CLI

Command

What it does

gtfa ask <term>

One term (default US, now 7-d), with optional --validate, --diff, --points, batch --from, --egress, per-request --timeout MS, and --pretty.

gtfa snapshot <term>

Multi-tier calibrated traffic, related queries, verdict, SVG charts, --egress, and per-request --timeout MS.

gtfa compare <kw> [<kw> ...]

Relative interest for 1–5 distinct keywords (also --query mode); optional --calibrate for batchVolume and --egress.

gtfa now --geo US

Trending Now by country; --hours is the Now window; supports --egress.

gtfa baselines [--sync]

Inspect the active MEKA calibration baseline catalog or manually sync the latest catalog from meka.im.

gtfa doctor

Check Node, Google Trends reachability, proxy, and one gpts US 24h fetch. --timeout MS bounds each network check; a challenge or HTTP 429 stops before the live fetch. --json for machines.

Full flags and examples: reference.

gtfa ask --pretty indents JSON for ordinary asks, validation batches, diffs, and errors while ask --validate without --json remains a table; --timeout MS applies to each Explore request rather than the whole call, so slow VMs can set it up to 60000.

How the numbers work

snapshot, ask --validate, and compare --calibrate put terms and MEKA regional anchors on one shared 0–100 scale, then compute traffic = round(score ÷ anchorLevel × dailySearches). These are anchor-based estimates, not measured Google search volume. Traffic stays null when no calibration exists or the anchor fails its reliability gate.

All surfaces (Library API, CLI, MCP, Apify Actor, and dsh) share the same MEKA v1 baseline catalog (59 Google Ads Keyword Planner anchors across 7 regions, revision 2026-11-19, synced once on initial install/first boot and updated manually via gtfa baselines --sync or dsh Settings). When trends_snapshot runs without a pinned anchor and round 1 is out of range, it automatically performs one second-round multi-tier MEKA retry and upgrades anchor / traffic if rescued.

Calibration baselines—including version 2 files and user-provided anchor rows—apply only to web searches in category 0. A CLI filter using another property or category can still return relative interest, but traffic / traffic7d objects remain with their searches/day fields set to null and an explanation; the version 2 format is unchanged. Only snapshot Popular/Rising rows retain estDaily for schema compatibility, and it is always null: those related lists do not share the primary term's scale. Ask tables do not contain estDaily.

Snapshot defaults to now 7-d (reusing the primary series for chart7d / traffic7d with no extra request). For a primary window other than now 7-d, it tries the separate 7-day request sequentially after the primary attempt finishes unless the primary ended in BLOCKED or RATE_LIMITED; other errors such as NETWORK_ERROR do not by themselves prevent that attempt. If the attempt is skipped, the empty chart, null traffic, and baseline metadata are returned with a warning. Caller cancellation or the overall deadline propagates through the whole snapshot and is not converted into those normal fallback fields.

Region

Default anchor

Baseline (searches/day)

Tiers in catalog

US (US)

sudoku

88,000/day, ±50%

10 anchors

Canada (CA)

sudoku

15,000/day, ±50%

7 anchors

United Kingdom (GB)

crossword solver

27,000/day, ±50%

8 anchors

Germany (DE)

Kreuzworträtsel

22,000/day, ±50%

8 anchors

France (FR)

sudoku

22,000/day, ±50%

8 anchors

Japan (JP)

テトリス

18,000/day, ±50%

8 anchors

Worldwide ("")

stopwatch

160,000/day, ±50%

10 anchors

Unsupported regions and sparse data retain null traffic. See regional values, sources and validation and Calibration and the anchor for overrides, version 2 baseline files, and null-traffic rules.

Docs

Client setup · Reference · MCP field guide (中文) · Architecture · Changelog · Baselines

Development

Tests use local fixtures and mocked transports; they do not call Google.

See automated checks and dsh compatibility testing for CI, settings interactions, and the real Host baseline checks.

npm install
npm test
npm run typecheck
npm run build
npm run trends -- --help

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers