ferric-fred-mcp
The ferric-fred-mcp server provides comprehensive access to the Federal Reserve Economic Data (FRED) service, exposing tools for querying economic data series, categories, releases, sources, and tags.
Series & Observations
Search for series by text with ordering, sorting, and result limits
Get series metadata (title, frequency, units, seasonal adjustment, popularity) by series ID
Fetch observations (date/value pairs) with optional date range, units transformation (e.g., percent change), frequency aggregation, sort order, and limit
Get recently updated series filtered by class (macro/regional) or a time window
Get vintage dates — the revision history of a series
Get categories, release, and tags associated with a specific series
Category Tree
Get a category by ID, list its children, and find related categories (cross-tree links)
List series in a category with ordering and pagination
List tag facets for a category's series and discover co-occurring tags
Releases
List all data releases and browse the release calendar across all releases
Get a specific release, its series, sources, publication dates, and nested table tree
List tag facets for a release's series and discover co-occurring tags within a release
Sources
List all data sources (e.g., Bureau of Economic Analysis), get source details, and list releases produced by a source
Tags
Browse or search the tag vocabulary (keywords like "gdp", "quarterly", "nsa")
Discover co-occurring tags globally or scoped to categories, releases, or search results
List series carrying specified tags for faceted discovery
Get tag facets for full-text series searches
All listing and search operations support pagination, sorting, and limiting results for efficient data access.
ferric-fred
A strongly-typed Rust client for FRED — the Federal Reserve Economic Data service from the Federal Reserve Bank of St. Louis — plus a CLI (with TUI charts) and an MCP server built on top of it.
ferric(iron oxide → rust) +FRED. Iron-clad, typed access to economic data.
Workspace
A Cargo workspace of three crates — each with its own README (the crates.io / docs.rs landing page) that carries the full usage detail:
Crate | Binary | What it is | Details |
| — | Strongly-typed async FRED client | |
|
| Command-line tool with | |
|
| MCP server exposing FRED to MCP clients |
Published versions (these badges are the source of truth — the crates version independently, so they can drift out of lockstep):
Consumers depend on the library by workspace path, so a breaking change in the library cannot compile-pass its consumers without updating them — that compile-time coupling is the primary "stay in sync" guarantee (versions are managed on top; see the ADRs).
Related MCP server: stooq-mcp
What it covers
The library wraps all of FRED's read endpoints — series and observations
(including ALFRED point-in-time / vintage data via a real-time window),
search, categories, releases (including the nested release-table tree, with
optional inline observation values), sources,
and tags — plus the GeoFRED / Maps API (regional data and the geographic
shape files to map it, ADR-0025) — behind
ergonomic builders, with newtype identifiers, typed enums for
FRED's closed value sets, a non-panicking error taxonomy, and auto-pagination
(Paginate::send_all walks an endpoint to exhaustion, Paginate::stream yields
lazily; --all on the CLI). See ADR-0020 and
ADR-0021.
GeoFRED support spans the library, CLI (fred geofred), and MCP
(get_regional_data, get_series_data, get_series_group) layers. The one
exception is the geographic shapes/file endpoint, which is library/CLI-only —
a large projected-GeoJSON blob is poor ergonomics for an MCP tool caller
(ADR-0025).
Pick an entry point:
Library —
cargo add ferric-fred; typed async access from your own code. See the crate README and docs.rs.CLI (
fred) —cargo install ferric-fred-cli; search, show metadata, print or chart observations in the terminal, browse categories, releases, sources, and tags, and pull GeoFRED regional data and map shapes (fred geofred). See the crate README orfred <command> --help.MCP server (
fred-mcp) —cargo install ferric-fred-mcp; 34 tools over stdio covering the same read surface, for MCP-capable clients (ADR-0010). Each tool declares input and output schemas plus behavioural annotations (ADR-0023). See the crate README.
The MCP server is listed and scored on Glama:
Development
A Nix flake provides a reproducible toolchain (nix develop, or direnv allow
once), but the project builds with a plain Rust toolchain too — Nix supplies the
environment, not the build (ADR-0008).
Contributor setup, the fmt/clippy/test/prose gate, the tracked git hooks, and the
workflow for adding an endpoint live in CONTRIBUTING.md.
CI (ci.yml) runs that same offline gate on every push and PR; a dormant
live.yml runs the live FRED tests once an Infisical machine identity is
configured (ADR-0016).
Benchmarks
Performance tooling from the org Tech Radar pilot (ADR-0026, issue #42):
# Deserialization microbenches (divan) — the observations parse hot path.
cargo bench -p ferric-fred --bench deserialization
# Same workload under criterion (the divan-vs-criterion baseline).
cargo bench -p ferric-fred --bench deserialization_criterion
# Headless `fred chart` render cost (divan + ratatui TestBackend, no tty).
cargo bench -p ferric-fred-cli --bench render
# CLI wall-clock timing (hyperfine): startup + a live fetch-and-render.
# The fetch benchmark needs FRED_API_KEY; startup runs offline.
scripts/bench-cli.sh # add --json DIR to export hyperfine JSONCI keeps the benches compiling on every PR (cargo bench --no-run), and a
separate bench.yml uploads results to Bencher (hosted
project ferric-fred) to track them over time and flag regressions on PRs.
Bencher has no divan adapter, so it ingests the criterion mirror
(rust_criterion) and hyperfine startup (shell_hyperfine); divan stays the
fast local harness. BENCHER_API_TOKEN comes from Infisical, so the upload is a
no-op until the machine identity is configured — see
ADR-0026.
Secrets
The client reads a free FRED API key from the FRED_API_KEY environment
variable (get one at https://fredaccount.stlouisfed.org/apikeys). Locally,
secrets are injected via Infisical + direnv
(ADR-0009):
cp .envrc.example .envrc # local, git-ignored entry point
infisical login # user auth (opens a browser)
infisical init # link this dir → project
direnv allow # load the shell + inject secrets on cd-inStore the key with infisical secrets set FRED_API_KEY="…" --env=dev --path=/shared.
No Infisical? Just set it directly in your git-ignored .envrc:
export FRED_API_KEY="…" — the library only reads the env var and has no
dependency on Infisical.
Architecture decisions
Design decisions are recorded as ADRs in docs/adr/. Start with
the index.
License
Dual-licensed under MIT OR Apache-2.0, at your option — the Rust ecosystem
default (ADR-0006). See LICENSE-MIT
and LICENSE-APACHE. Unless you state otherwise, any
contribution you submit is licensed under the same dual terms (see
CONTRIBUTING.md).
This covers our code; FRED data itself is subject to the St. Louis Fed's terms of use, and you supply your own API key — the project ships no data and no key.
Available Tools
34 toolsget_categoryARead-onlyIdempotent
Fetch a FRED category by its id (0 is the root of the category tree): its name and parent category id.
Inputs: category_id (required). Returns: id, name, parent_id
get_category_childrenARead-onlyIdempotent
List the child categories of a FRED category (use id 0 for the top-level categories). The primary way to walk the category tree downward.
Inputs: category_id (required). Returns: count, children, category_id
get_category_seriesARead-onlyIdempotent
List the FRED series that belong to a category, with pagination metadata (total count, offset, limit). Supports ordering, sort direction, and a result limit.
Inputs: category_id (required), sort, limit, order_by. Returns: count, limit, offset, series
get_category_tagsARead-onlyIdempotent
List the tags used by the series in a FRED category (the tag facets for browsing a category), with pagination metadata. Optionally filter by search text; supports sort direction and a result limit.
Inputs: category_id (required), sort, limit, search_text. Returns: tags, count, limit, offset
get_observationsARead-onlyIdempotent
Fetch a FRED series' observations (date/value pairs, each with its ALFRED real-time period). Supports an optional date range, a units transform, aggregation to a lower frequency, sort order, and a result limit. For point-in-time/vintage (ALFRED) data, set realtime_start/realtime_end (both together; same date = the series as known on that day) and/or vintage_dates.
Inputs: series_id (required), end, sort, limit, +7 more. Returns: count, series_id, observations
get_regional_dataARead-onlyIdempotent
GeoFRED / Maps: fetch a region cross-section for a series group — the value in every region (state, county, MSA, country, or BEA region) on a given date. All arguments are required: series_group id, region_type, date, units (a free-text measurement label FRED echoes into the title, e.g. Dollars), frequency, and season. The result nests everything under a top-level meta object (FRED's own envelope, mirrored faithfully): the dated per-region values live under meta.data, which maps each observation date to a list of {region, code, value, series_id}; alongside them sit the display labels meta.title, meta.units, meta.region, meta.seasonality, and meta.frequency (see the output schema for the full shape). Size caveat: FRED returns the full cross-section with no limit or paging, so region_type county or msa yields thousands of regions (a county cross-section can exceed 250,000 characters) — prefer state, bea, or country unless you need that granularity.
Inputs: date (required), units (required), season (required), frequency (required), +2 more. Returns: meta
get_releaseARead-onlyIdempotent
Fetch a FRED data release by its id (e.g. 53 = Gross Domestic Product): its name, press-release flag, and link.
Inputs: release_id (required). Returns: id, link, name, press_release
get_release_datesARead-onlyIdempotent
List the publication dates of ONE FRED release (its calendar), with pagination metadata. Oldest first by default; supports sort direction, a result limit, and including dates that have no data yet (e.g. scheduled future releases).
Inputs: release_id (required), sort, limit, include_dates_with_no_data. Returns: count, limit, offset, release_dates
get_releasesARead-onlyIdempotent
List FRED data releases (publications such as "Gross Domestic Product"), with pagination metadata. A browse axis parallel to categories. Supports sort direction and a result limit.
Inputs: sort, limit. Returns: count, limit, offset, releases
get_releases_datesARead-onlyIdempotent
List the publication dates of ALL FRED releases — a release calendar across FRED — with pagination metadata. Each entry names its release. Newest first by default; supports sort direction, a result limit, and including dates that have no data yet.
Inputs: sort, limit, include_dates_with_no_data. Returns: count, limit, offset, release_dates
get_release_seriesARead-onlyIdempotent
List the FRED series published in a release, with pagination metadata (total count, offset, limit). Supports ordering, sort direction, and a result limit.
Inputs: release_id (required), sort, limit, order_by. Returns: count, limit, offset, series
get_release_sourcesARead-onlyIdempotent
List the FRED data sources a release draws from (the reverse of get_source_releases). Returns the full unpaginated list wrapped as {count, sources}.
Inputs: release_id (required). Returns: count, sources
get_release_tablesARead-onlyIdempotent
Fetch a FRED release's table tree — the nested layout (sections, tables, and the series rows beneath them) it uses to present its series. Optionally scope to the subtree rooted at one element id, and optionally fold each series row's observation value (at observation_date, or FRED's latest) into the tree via include_observation_values. Returns the tree as structured JSON, with each element's children nested under it. Note: element_id takes precedence over release_id — FRED resolves the element by its own id, so an element from another release yields that release's subtree. Note: each returned row's observation_date is FRED's display label (e.g. "Jun 2026"), not an ISO YYYY-MM-DD date like the inputs — it is not round-trippable back into any date parameter.
Inputs: release_id (required), element_id, observation_date, include_observation_values. Returns: name, roots, element_id
get_release_tagsARead-onlyIdempotent
List the tags used by the series in a FRED release (the tag facets for browsing a release), with pagination metadata. Optionally filter by search text; supports sort direction and a result limit.
Inputs: release_id (required), sort, limit, search_text. Returns: tags, count, limit, offset
get_seriesARead-onlyIdempotent
Fetch metadata for a FRED series by its id (e.g. GNPCA, UNRATE): title, frequency, seasonal adjustment, units, observation date range, and popularity.
Inputs: series_id (required). Returns: id, notes, title, units, +6 more
get_series_categoriesARead-onlyIdempotent
List the categories a FRED series belongs to (the reverse of get_category_series): given a series id, where it sits in the category tree.
Inputs: series_id (required). Returns: count, categories
get_series_dataARead-onlyIdempotent
GeoFRED / Maps: fetch one regional series' values across regions, optionally over time. Give a regional series_id; with no date, FRED returns the most recent. Set date for a single date, or start_date for every date from then on. The result nests everything under a top-level meta object (FRED's own envelope, mirrored faithfully): the dated per-region values live under meta.data, which maps each observation date to a list of {region, code, value, series_id}; alongside them sit the display labels meta.title, meta.units, meta.region, meta.seasonality, and meta.frequency (see the output schema for the full shape).
Inputs: series_id (required), date, start_date. Returns: meta
get_series_groupARead-onlyIdempotent
GeoFRED / Maps: fetch the series-group metadata for a regional series — pass a regional series_id and get the group it belongs to (title, region type, units, frequency, and the span of dates it covers).
Inputs: series_id (required). Returns: title, units, season, max_date, +4 more
get_series_releaseARead-onlyIdempotent
Fetch the release a FRED series belongs to (the reverse of get_release_series): given a series id, its publishing release.
Inputs: series_id (required). Returns: id, link, name, press_release
get_series_search_tagsARead-onlyIdempotent
List the tags on the series matching a full-text search (its tag facets, for narrowing the search down), with pagination metadata. Optionally filter the tags by text; supports sort direction and a result limit.
Inputs: search_text (required), sort, limit, tag_search_text. Returns: tags, count, limit, offset
get_series_tagsARead-onlyIdempotent
List the tags attached to a FRED series (the reverse of get_tags_series): given a series id, what keywords classify it.
Inputs: series_id (required). Returns: tags, count, limit, offset
get_series_updatesARead-onlyIdempotent
List the FRED series updated most recently (a "what changed" feed, ordered by last-updated time), with pagination metadata. Optionally narrow to macro or regional series, or to a start_time/end_time update window (both required together, YYYY-MM-DDTHH:MM in FRED's timezone).
Inputs: limit, filter, end_time, start_time. Returns: count, limit, offset, series
get_series_vintagedatesARead-onlyIdempotent
List a FRED series' vintage dates — the dates on which it was revised or newly released, i.e. how the series looked at each point in time. Supports sort direction and a result limit.
Inputs: series_id (required), sort, limit. Returns: count, limit, offset, vintage_dates
get_sourceARead-onlyIdempotent
Fetch a FRED data source by its id (e.g. 18 = U.S. Bureau of Economic Analysis): its name and link.
Inputs: source_id (required). Returns: id, link, name
get_source_releasesARead-onlyIdempotent
List the releases produced by a FRED data source, with pagination metadata. Supports sort direction and a result limit.
Inputs: source_id (required), sort, limit. Returns: count, limit, offset, releases
get_sourcesARead-onlyIdempotent
List FRED data sources (the organizations that produce releases, e.g. the Bureau of Economic Analysis), with pagination metadata. Supports sort direction and a result limit.
Inputs: sort, limit. Returns: count, limit, offset, sources
get_tagsARead-onlyIdempotent
Browse or search FRED's tag vocabulary (keywords such as "gdp", "quarterly", "nsa" used to classify series). Optionally filter by search text. Returns tags with their group, popularity, and series count.
Inputs: sort, limit, search_text. Returns: tags, count, limit, offset
get_tags_seriesARead-onlyIdempotent
List the FRED series carrying ALL of the given tags (faceted discovery), with pagination metadata. Supports ordering, sort direction, and a result limit.
Inputs: tag_names (required), sort, limit, order_by. Returns: count, limit, offset, series
search_seriesARead-onlyIdempotent
Search FRED for series matching text. Returns the matching series along with pagination metadata (total match count, offset, limit).
Inputs: text (required), sort, limit, order_by. Returns: count, limit, offset, series
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Some overlap exists among the many related-tag and reverse-lookup tools (get_related_tags vs get_category_related_tags vs get_release_related_tags vs get_series_search_related_tags; get_release_dates vs get_releases_dates), so agents could misselect. Detailed descriptions and clear resource prefixes help, but the boundaries aren't instantly obvious.
Almost all tools follow the get_<resource>_<detail> pattern, and even search_series is verb_noun. The minor deviations are the plural variants get_releases_dates and the singular get_release_dates, plus search_series, but overall the naming is predictable.
34 tools is a large surface, exceeding the 25+ threshold, and many are near-identical in shape (every resource gets tags/related_tags/series endpoints). While each maps to a distinct FRED endpoint, the set feels heavy for an agent to navigate.
The tool set comprehensively mirrors FRED's read-only API: categories, releases, sources, series, tags, observations, regional data, vintages, and search all have coverage. No obvious dead ends or missing CRUD exist because FRED has no write operations.
Maintenance
Related MCP Connectors
Hosted MCP server for SEC, FRED, Polymarket, Deribit, OKX, and FMP.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Multi-tenant FastMCP server for Charles Schwab brokerage data, monetized via DPYC Tollbooth
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
Related MCP Servers
- FlicenseBqualityDmaintenanceA Model Context Protocol server that provides tools to search and retrieve economic data series from the Federal Reserve Economic Data (FRED) API.211-
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server written in Rust that fetches stock price data from stooq.com.9-
- AlicenseNot gradedqualityBmaintenanceAn MCP server that wraps the Federal Reserve Economic Data (FRED) API, providing access to over 800,000 economic time series like GDP and unemployment. It enables AI agents to search for data, retrieve metadata, and fetch historical observations directly from the St. Louis Fed.Apache 2.0
- FlicenseCqualityDmaintenanceEnables users to query and explore economic data from FRED, supporting tools for searching series, retrieving observations, and browsing categories. It provides comprehensive access to financial datasets, including GeoFRED maps and raw endpoint passthrough for advanced research.401-