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:

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: FRED MCP Server

What it covers

The library wraps all of FRED's read endpoints — series and observations, search, categories, releases (including the nested release-table tree), sources, and tags — 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.

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, and browse categories, releases, sources, and tags. See the crate README or fred <command> --help.

• MCP server (fred-mcp) — cargo install ferric-fred-mcp; 31 tools over stdio covering the same read surface, for MCP-capable clients (ADR-0010). 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 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).

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.