@macroradar/mcp

A zero-dependency Model Context Protocol server for MacroRadar's free US macro data API. Gives any MCP client (Claude Desktop, Claude Code, and others) tools for:

• get_catalog — every tracked series with ids, units, and license posture
• get_latest / get_series — observations with 10y/30y percentiles and z-scores, by FRED-style id (UNRATE) or slug (unemployment-rate)
• get_series_as_of — what a series read on a past date, from the vintage archive, with known_at / not_yet_published / no_archive distinguished rather than collapsed to null
• get_regime — MacroRadar's multi-dimensional macro regime read
• get_regime_history — that regime's five-way probability path over time, each point from a walk-forward refit as of that date
• get_recession_probability — walk-forward 6-month recession probability
• get_sentiment — the 0-100 sentiment composite with causal daily history
• get_whats_moving — every indicator's latest move ranked by rarity against its own history, with a checkable sentence per row
• get_ranked — a fixed list of major asset-class series ranked by distance from the midpoint of their own trailing 10-year percentile
• get_breadth — cross-country tail breadth by concept: how many of the observed economies sit in their own high or low tail together
• get_episodes — derived episode spans (inversions, bear markets, rate cycles), including the open spans ranked by running duration
• get_event_windows — FOMC decision-day moves, ranked per series
• get_calendar — releases, FOMC meetings, ECB/BoE/BoJ decisions, and US trade actions from the institutions' own schedules
• get_daily_log — the macro record of any date, decades back
• get_policy_regimes — sanctions, tariff and export-control programmes as spans, each dated from a cited instrument
• get_studies — conditional history: every past window where stated macro conditions held, and what followed each, as a count and a distribution — never a probability or a forecast
• run_study — the same conditional-history question, ad hoc: state your own conditions and measured expression (the same grammar compute addresses) and get back N matched windows, the outcome distribution, and the windows themselves. A 422 refusal is returned verbatim.
• run_exposure — run_study for a weighted, long-only basket (up to 10 members) instead of one series: the same conditions, rebalanced at the start of every matched window, with the basket's own distribution of outcomes.
• compute — any expression the macro grammar can express (FEDFUNDS, CPIAUCSL.yoy, FEDFUNDS~minus~CPIAUCSL.yoy), returned with the plan that produced it; a refusal names exactly what would have been wrong
• get_claims — the claims ledger: the rule and recompute steps behind every MacroRadar figure

Twenty-one tools in total (tools/list is the count that matters — it is verified by npm test on every change, so this number cannot go stale the way a hand-typed count elsewhere in the repo once did).

All values are historical indicators, not investment advice. Every value returned over a redistributable (public-domain, US-government) series may be quoted in public and verified for free directly against MacroRadar's own API. Licensed series (VIX, Case-Shiller, and others) never leave the raw level unmarked: get_series, get_latest, and get_series_as_of return metadata and a chart link instead of a value, and derived-statistic tools (get_whats_moving, get_episodes, get_event_windows, get_ranked) return their computed percentile, z-score or rank with a value_note stating that the underlying level is withheld. run_study and run_exposure withhold the same way: raw values inside windows come back null for a licensed series, and recompute.licensed_series names which ones. Either way the server treats it as an answer, not an error, and never a silent gap.

Where a response corresponds to one written-down rule in the claims ledger (apps/web/lib/claims.ts), its meta object also carries claim_id and recompute_url — the address (a /compute, /studies or /api/v1 page) that reproduces the number. Not every tool has one yet; see docs/decisions/2026-08-28-mcp-attribution-envelope.md for which do and why the rest honestly omit it rather than guess.

Setup

Requires Node 18+. No install step, no API key.

Claude Desktop / Claude Code config (mcpServers):

{
	"mcpServers": {
		"macroradar": {
			"command": "npx",
			"args": ["-y", "@macroradar/mcp"]
		}
	}
}

Or run it from a checkout:

{
	"mcpServers": {
		"macroradar": {
			"command": "node",
			"args": ["/path/to/macroradar/packages/mcp/index.mjs"]
		}
	}
}

How it works

Plain Node stdio, one JSON-RPC message per line, no dependencies — the whole server is one file (index.mjs). It calls the public API documented at https://www.macroradar.io/developers (cached hourly, attribution requested). MACRORADAR_API_BASE overrides the API base URL. npm test runs a full protocol handshake against a local stub.