How does an AI agent get npm trend data?

Install Trends MCP, then ask the agent, using TrendsMCP, to call get_growth with source npm and the exact package name, such as zod or @tanstack/react-query. MCP get_trends or REST get_time_series returns the weekly series. Display names such as React Query are the wrong keyword.

How is this different from api.npmjs.org/downloads?

npm’s own downloads API returns raw counts for date ranges the caller specifies. Trends MCP normalizes to a 0-100 index, computes percent_growth, and uses the same payload shape as google search or tiktok. Cross-source comparison is the point.

Can one call compare two packages?

No. One keyword per get_growth call. Two packages are two requests. Adding google search on one name is a second source on that name, billed separately. Several windows such as 6M and 1Y ride in one call.

Should the agent scrape npm-stat or libraries.io?

Not for this job. Those sites are other UIs. The agent should call the MCP. A crawl MCP still wins “what does this README HTML say.” GitHub MCP still opens the issue.

npm Trends API for AI Agents

An npm trends API for AI agents is Trends MCP with source npm, not a second scrape of npm-stat. After the client has a Bearer key on https://api.trendsmcp.ai/mcp, the agent calls get_growth with the exact package name. Scoped packages keep the @scope/name form. Case matters (react, not React). get_trends (REST get_time_series) returns the weekly series, about five years where points exist. Optional data_mode daily on REST covers the last 30 days, per the npm source page.

The REST-shaped source page is npm API. The product view is npm trends. This H1 is the agent job those pages do not use. Cursor host JSON: Trends MCP for Cursor. GitHub board pairing: GitHub trending MCP for Cursor.

Exact names, then stop guessing

zod is a package. colinhacks/zod is a repo slug. Sending the slug into source npm is how the series comes back empty. @babel/core is a package. Babel is a brand. The agent should read package.json or the registry name, then call the tool.

get_growth(keyword="zod", source="npm", percent_growth=["6M", "1Y"])
get_growth(keyword="zod", source="npm, google search", percent_growth=["6M"])
get_top_trends(type="GitHub", limit=25)

Type GitHub is the daily trending repositories board. No keyword. Default limit 25. It is not npm. A repo can trend for a day while downloads are quiet. A package can climb while the repo is off the board. Write both, or write one and label it.

Empty: not_found or data_unavailable, often a display title used as a keyword. Fail closed. Do not ask the agent to estimate downloads. Low-volume packages print huge percents on tiny baselines. Quote recent_value and baseline_value.

Say “using TrendsMCP.” An agent that only has GitHub MCP will open issues and skip npm demand. An agent that only has browsing will retrieve npm-stat screenshots.

Agent sequences that fit the free month

A sequence that works: one GitHub board if the ticket started from trending repos, then get_growth on npm for one or two exact names. Two or three requests. A sequence that fails: growth on every name that “looks like a package,” then a web search of npmjs.com “to confirm.” That is how the free 100-request plan dies before the PR note is written.

Two comparison packages are two npm calls. Google Search on the library phrase is a third source, a different object. react on npm is downloads. react on google search is public interest. Split the sentence in the note.

REST from CI: POST https://api.trendsmcp.ai/api with mode get_growth, source npm, keyword the name. The IDE does not need to be open. Wrapping a chat agent as cron still bills the same math and still needs a launch.

.cursorrules or CLAUDE.md can pin source npm, the exact-name rule, and a cap of two packages. They should not pin this morning’s trending repo titles. The GitHub board turns over.

What this API will not do

It will not return dependents, vulnerability counts, or license text. It will not replace npm view. It will not replace GitHub stars-over-time. Official npm downloads remain available at api.npmjs.org/downloads for raw counts. Use that when the ticket asks for absolute downloads. Use Trends MCP when the ticket asks for a 0-100 series next to Google or TikTok.

libraries.io, npm-stat, and similar UIs remain human browsers. A crawl MCP can fetch a URL. Trends MCP will not.

Free 100 requests per month. Starter $19 / 1,000. Pro $49 / 5,000. Business $199 / 25,000. Annual 20 percent off. Pricing. Connecting is free. One npm growth call is one request even with 6M and 1Y in the same payload.

401: www OAuth URL in Cursor or Claude Code. invalid_source: type GitHub sent as a keyword source. Cursor wants url plus transport http. Claude Code flags belong in a fenced command on that client page.

If the next turn is “open the issue,” stop using Trends MCP for that turn. GitHub MCP owns the repo verbs. Pair them. Do not uninstall one because the other appeared.

What belongs in the agent note

Cite the tool. A useful note says source npm, keyword zod, windows 6M and 1Y, both index values, and recent_date if present. A weak note says “zod is exploding.” The second sentence is how invented adoption lands in git.

Daily REST mode, when the ticket asked for the last 30 days, is a different grain from the weekly default. Do not treat a daily 30-day slope as a five-year weekly slope. If the payload omitted daily points, do not invent them.

Scoped packages fail when the agent strips @ or splits on /. @tanstack/react-query is one keyword. tanstack is a different package if it exists, and a miss if it does not. Read the lockfile.

A second source on the same name, google search or tiktok, is how an agent answers “is this only a downloads story.” That is the job npm’s raw API does not do. It is also why this page is not a clone of the npm REST source page.

401 and invalid_source still apply. Cursor is a weak cron. Nightly npm growth belongs on REST. The proving call in Agent or Claude Code is the connect test, not the production monitor.

If Agent starts quoting GitHub star counts from this payload, stop. Stars are not in the npm series. Open GitHub MCP or the repo page. Mixing the two without labels produces a review comment that looks cited and still lacks a recent_date.