gtfa-mcp
Integrates with Google Trends to provide search-interest signals for terms, including calibrated searches/day snapshots, comparative relative interest across keywords, related and rising queries, regional interest, and Trending Now data by country.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 --prettyBuilding 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/mcpCheck both package-download and data-fetch connectivity:
curl -I https://github.com
curl -I https://trends.google.comIf 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-agentAfter 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>": truepnpm'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.
Term gallery
MCP tools
Tool | What it does |
| Interest, Popular/Rising queries, regions, optional verdict and diff (default: |
| Calibrated searches/day with multi-tier MEKA auto-calibration (automatic 2nd-round tier retry when out of range), anchor/traffic/calibration blocks, verdict, |
| Relative 0–100 interest for 1–5 distinct keywords on one shared scale; optional |
| 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 |
| One term (default |
| Multi-tier calibrated traffic, related queries, verdict, SVG charts, |
| Relative interest for 1–5 distinct keywords (also |
| Trending Now by country; |
| Inspect the active MEKA calibration baseline catalog or manually sync the latest catalog from |
| Check Node, Google Trends reachability, proxy, and one |
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 ( |
| 88,000/day, ±50% | 10 anchors |
Canada ( |
| 15,000/day, ±50% | 7 anchors |
United Kingdom ( |
| 27,000/day, ±50% | 8 anchors |
Germany ( |
| 22,000/day, ±50% | 8 anchors |
France ( |
| 22,000/day, ±50% | 8 anchors |
Japan ( |
| 18,000/day, ±50% | 8 anchors |
Worldwide ( |
| 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 -- --helpLicense
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Google Trends for agents: interest over time, by region, rising queries, Trending Now. No API key.
Bulk Google Trends: interest over time, regions, rising queries and plain-English trend summaries.
Google Trends: interest over time, by region and city, related and rising queries, and Trending Now in any country. Compare keywords on one scale. Runs on Apify, $1 per 1,000 keyword reports.
Google Trends data as JSON: interest over time, rising and top queries, regions, Trending Now.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access Google Trends data for comparing keywords, discovering trending searches, and analyzing regional interest through natural language.2MIT
- AlicenseBqualityDmaintenanceEnables Claude to query Google Trends data such as keyword interest, related queries, and regional popularity, with robust proxy rotation to bypass Google's anti-bot measures.558 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query Google Trends data, including search interest over time, regional breakdowns, trending searches, and keyword ideas.MIT
- AlicenseAqualityCmaintenanceEnables AI agents to query live trend data and historical search volume across 30+ platforms like Google, TikTok, YouTube, Amazon, and Reddit, including growth comparisons and top-ranking trends.317MIT