MCP server

Give an AI agent (Claude Code, Claude Desktop, Cursor) direct tools to query the free Pulse API.

earlyforge-trends wraps the Pulse API as MCP tools, so an AI agent can query EarlyForge's trend data directly instead of being told to call a REST endpoint. It's an authenticated, verbatim mirror of the same free, anonymous data already shown on pulse.earlyforge.ai — same daily snapshot, same trend count, same fields, nothing more.

This server runs locally only, as a stdio process you launch yourself — there is no cloud-hosted https://mcp.earlyforge.ai endpoint yet. Every config below starts the same local Python script; the only thing that differs is which client file it goes in.

Source: tools/mcp-earlyforge — read the package's own README for anything not covered here.

Tools

top_trends(date?, locale?) — same snapshot as the Pulse homepage.
trends_by_region(region, date?, locale?)
trends_by_category(category, date?, locale?)
get_trend(trend_id) — same payload as the public trend detail page.

These 4 need an EARLYFORGE_API_KEY. Two more tools need no account or API key at all — they just read this documentation site's public llms.txt / llms-full.txt routes:

list_docs() — the full documentation index (titles + URLs).
read_docs() — the entire documentation, concatenated.

It also exposes an MCP prompt, editorial_watch(country?, sector?), that walks an agent through building a trend-watch briefing with the tools above — and tells the agent to be upfront if the user asks for something beyond this free tier (real-time monitoring, the full country/category catalog), pointing to earlyforge.ai/pricing rather than inventing capabilities.

Requirements

Any EarlyForge account and an API key from Settings → API Keys in the console — Pulse access is free, no paid plan required. Keys look like ef_live_xxxxxxxxxxxxxxxx and are shown once at creation.
Python 3.10+.

Install

cd tools/mcp-earlyforge
pip install -r requirements.txt

Configure

Env var	Required	Default
`EARLYFORGE_API_KEY`	yes	—
`EARLYFORGE_API_BASE`	no	`https://api.earlyforge.ai` (set to your local gateway, e.g. `http://localhost:8000`, for dev)

Run standalone

EARLYFORGE_API_KEY=ef_live_xxx python server.py

Add to your client

One-liner (local stdio server, env var passed with --env):

claude mcp add earlyforge-trends --env EARLYFORGE_API_KEY=ef_live_xxxxxxxxxxxxxxxx -- python /absolute/path/to/tools/mcp-earlyforge/server.py

Use -s project instead of the default -s local to share the entry via .mcp.json with everyone who clones the repo (don't commit your real key if you do — use a placeholder and let each teammate set their own EARLYFORGE_API_KEY).

Verify it's registered: claude mcp list / claude mcp get earlyforge-trends. Remove it: claude mcp remove earlyforge-trends.

Any other stdio-capable MCP client (VS Code's MCP extension, etc.) takes the same three pieces of information: command: python, args: ["/absolute/path/to/tools/mcp-earlyforge/server.py"], and the EARLYFORGE_API_KEY env var. Consult your client's docs for where that JSON block goes.

For local development against a gateway running via docker compose up, add "EARLYFORGE_API_BASE": "http://localhost:8000" to env in any of the configs above (adjust if your local Traefik/port setup differs).

Error handling

A revoked/disabled key, an unknown trend_id, and a temporarily unavailable Pulse upstream are all surfaced as plain tool-call error messages (not stack traces) — the same 401 / 404 / 502 responses documented in the OpenAPI contract. This surface has no monthly quota (it's free Pulse data), so there's no quota-exhaustion case to handle.

Going further

This server only covers the free Pulse snapshot — it's the entire public API, on every plan. EarlyForge's paid plans add real-time trend detection across the full catalog of countries and categories inside the app itself (console only, not via this server) — see the pricing page for that upgrade path.