Skip to main content
Glama

ferric-fred

CI License: MIT OR Apache-2.0 ferric-fred MCP server

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

ferric-fred

—

Strongly-typed async FRED client

README · docs.rs

ferric-fred-cli

fred

Command-line tool with ratatui TUI charts

README

ferric-fred-mcp

fred-mcp

MCP server exposing FRED to MCP clients

README

Published versions (these badges are the source of truth — the crates version independently, so they can drift out of lockstep):

ferric-fred ferric-fred-cli ferric-fred-mcp

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 or fred <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:

ferric-fred MCP server

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 JSON

CI 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-in

Store 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 tools
get_categoryA
Read-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_childrenA
Read-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_seriesA
Read-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_tagsA
Read-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_observationsA
Read-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_dataA
Read-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_releaseA
Read-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_datesA
Read-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_releasesA
Read-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_datesA
Read-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_seriesA
Read-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_sourcesA
Read-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_tablesA
Read-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_tagsA
Read-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_seriesA
Read-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_categoriesA
Read-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_dataA
Read-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_groupA
Read-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_releaseA
Read-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_tagsA
Read-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_tagsA
Read-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_updatesA
Read-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_vintagedatesA
Read-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_sourceA
Read-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_releasesA
Read-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_sourcesA
Read-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_tagsA
Read-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_seriesA
Read-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_seriesA
Read-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

    A3.9/5.0

    Scored across 34 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server written in Rust that fetches stock price data from stooq.com.
      9
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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
    • F
      license
      C
      quality
      D
      maintenance
      Enables 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.
      40
      1
      -