Skip to main content
Glama
Sign In
meka-im

gtfa-mcp

by meka-im
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote
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.

Term gallery

Related MCP server: Google Trends MCP

Install

Requires Node.js 20+.

npm install -g github:meka-im/google-trends-for-agent
gtfa --help
gtfa-mcp   # stdio MCP server

The package installs two commands: gtfa for the CLI and gtfa-mcp for the MCP server.

Quick start

One snapshot, calibrated searches/day:

npx gtfa snapshot Sora --geo US --json --pretty

The MCP server runs over stdio. Point a client at the published package:

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

MCP tools

Tool

What it does

trends_ask

Interest, Popular/Rising queries, regions, optional verdict and diff.

trends_snapshot

Calibrated searches/day, anchor/traffic blocks, verdict, chart7d / traffic7d.

trends_compare

Relative 0–100 interest for 2–5 keywords on one shared scale.

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, with optional --validate, --diff, --points, and batch --from.

gtfa snapshot <term>

Calibrated traffic, related queries, verdict, and SVG charts.

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

Relative interest for 1–5 keywords (also --query mode).

gtfa now

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

Full flags and examples: reference.

How the numbers work

  • snapshot puts the term and anchor on one shared 0–100 scale, then calibrates with traffic = round(score ÷ anchorLevel × dailySearches). The built-in US anchor is gpts at 550/day (about 16.5k/month, ±50%).

  • Numeric traffic stays null unless the anchor has a non-gap point, anchorLevel ≥ 1, and at least 25% of non-gap points are nonzero. Sparse 24-hour windows can fail that gate; 7-day windows are denser.

  • These are anchor-based estimates, not measured Google search volume. When the request is not now 7-d, traffic7d / chart7d come from a separate 7-day fetch; for now 7-d they reuse the primary snapshot and chart.

  • Failures stay explicit: ok, status, and error.code replace invented numbers, and partial results are reported rather than hidden.

Docs

Development

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

npm install
npm test          # 194 tests
npm run typecheck
npm run build
npm run trends -- --help

Node.js 20+ is required. npm run build writes JavaScript and declarations to dist/. The library entrypoint (src/index.ts) exports the client, snapshot, calibration, chart, Trending Now, and time-zone APIs.

License

MIT. See LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers