Skip to main content
Glama

fiscus

US economic data MCP server — curated catalog of macro, Treasury, and financial sources with the caveats attached

fiscus leads with the plumbing that generic macro-data wrappers usually omit: Treasury FiscalData, MSPD, DTS, SOMA, Z.1 semantics, TIC, and OFR money-fund monitors — alongside BEA national accounts, BLS labor series, CBO baselines, NY Fed reference rates, TreasuryDirect auctions, and selected FRED series. Curated fetches are catalog-selected and labeled with reviewed units and known footguns; explicitly uncurated routes remain labeled as such. Fetches are cached with immutable provenance. Sources that reject automated clients (bls.gov tables, cbo.gov workbooks) are cataloged as browser-download-only so agents get an explicit diagnosis instead of a mysterious 403.

Install

uv tool install git+https://github.com/smkwray/fiscus.git

For a one-off invocation without installation:

uvx --from git+https://github.com/smkwray/fiscus.git fiscus find-series "Treasury General Account"

Related MCP server: econstats-mcp

Zero-key quickstart

FRED public CSV and Treasury FiscalData work without credentials.

fiscus find-series "TGA Wednesday level"
fiscus get-series fred.wdtgal --start 2024-01-01
fiscus fiscaldata-query fiscaldata.dts_operating_cash_balance \
  --param 'filter=record_date:gte:2024-01-01' \
  --param 'sort=record_date' \
  --max-pages 2

Set FRED_API_KEY to use the official FRED observations API instead of the public graph CSV path and to request historical ALFRED information snapshots, BEA_API_KEY for BEA national-accounts tables (required), and BLS_API_KEY to raise BLS query limits (optional). Keys are read from environment variables only; the MCP server can be launched with uv run --env-file pointing at a private env file.

For a FRED series, --vintage-as-of YYYY-MM-DD selects the information available to ALFRED on one closed past date. --start and --end remain inclusive observation-date bounds; they are never treated as vintage dates. Today and future information dates are rejected because today's information set remains mutable.

MCP server

The server has a dedicated executable so an interactive fiscus command never appears to hang on stdio:

uvx --from git+https://github.com/smkwray/fiscus.git fiscus-mcp

Generic client configuration:

{
  "mcpServers": {
    "fiscus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/smkwray/fiscus.git", "fiscus-mcp"]
    }
  }
}

From a checkout, use uv run fiscus-mcp instead.

Cache-backed tool results contain an artifact descriptor, not a server-local pathname. MCP clients read the exact payload through the read-only resource template fiscus-cache://artifact/{cache_key}. The resource returns byte-exact content, including binary workbooks and archives; use the descriptor's mime_type and filename when saving or interpreting it. This keeps the nine read-only tools focused on economic-data operations rather than adding a server-side export tool whose path would still be inaccessible to a remote MCP client.

Command surface

fiscus find-series QUERY
fiscus get-series DATASET_ID [--start DATE] [--end DATE] [--vintage-as-of DATE]
fiscus bea-nipa-table TABLE_ID {A,Q,M} START_YEAR END_YEAR
fiscus fiscaldata-query DATASET_ID [--param KEY=VALUE] [--max-pages N]
fiscus get-file DATASET_ID
fiscus z1-series CODE KIND [--start DATE] [--end DATE]
fiscus soma-holdings [--asof DATE] [--cusip CUSIP]
fiscus source-caveats DATASET_ID
fiscus provenance CACHE_KEY
fiscus cache export CACHE_KEY --out PATH
fiscus cache migrate-v1 [--from PATH]
fiscus catalog lint
fiscus mcp

Call find-series before a fetch command. Dataset identifiers are curated catalog IDs — but coverage is not limited to the catalog:

  • Uncataloged passthrough: any FRED or BLS series is fetchable as fred.<SERIES_ID> / bls.<SERIES_ID>. Keyed current FRED requests derive units, seasonal adjustment, annualization, and a conservative unit_class from official series metadata. Historical uncataloged ALFRED snapshots label their units as unverified for the requested vintage, since current metadata can describe a different reference base or unit regime. Detected annual-rate series receive an explicit interpretation caveat; the keyless FRED graph route and current BLS data route report annualization as unknown and warn the caller to verify before treating observations as period flows. BLS observation footnotes, including preliminary flags, are retained as JSON in the CSV footnotes column. Every passthrough remains marked "uncataloged — no curated caveat review." The catalog is for caveats, not coverage.

  • Upstream search fallback: when find-series has no complete catalog match, it appends candidates from FRED's own search (requires FRED_API_KEY), clearly marked uncurated, so an empty result is a lead rather than a dead end.

  • Curated release files: Census vintage files and archived BLS releases carry a logical release id and representation. Their immutable source identity appends the SHA-256 of exact downloaded bytes, so a correction at the same URL creates a new revision while ETag and Last-Modified remain transport metadata.

  • Z.1 package discovery: find-series QUERY --family z1 searches the current official package data dictionary without a key and returns the exact z1-series CODE KIND call for uncataloged matches.

  • BEA NIPA table access: find-series QUERY --family bea falls back to BEA's source-reported NIPA table inventory. The inventory is cached in Fiscus's platform SQLite cache and refreshed once before an apparent table/frequency miss is rejected. bea-nipa-table fixes datasetname=NIPA, requires explicit inclusive years, and returns per-line observed coverage. Uncurated results and responses omit reviewed history, units, and verified_on; an exact cataloged table/frequency pair adds a separate curation overlay. get-series bea.nipa_t10106 remains a deprecated one-release alias.

  • Local artifacts: private overlay entries can register files already on disk via the local_file executor (endpoint.local_path) — served in place with a content-hash provenance block, never copied. See catalog/CONTRIBUTING.md.

z1-series additionally accepts any mnemonic from the official Z.1 CSV package (including FRED-style BOGZ1 aliases) and enforces the mnemonic's official series-type prefix, including transactions, levels, changes, revaluations, other volume changes, seasonal factors, growth rates, and indexes. One package download per release serves every series, and uncataloged mnemonics are labeled from the package's own data dictionary. soma-holdings resolves the latest weekly snapshot date before consulting the cache, so "latest" never freezes to a stale snapshot. provenance re-emits the immutable manifest and artifact descriptor for a full cache key or unique prefix.

For z1-series, KIND must be the mnemonic's matching official prefix: FA, FC, FG, FI, FL, FR, FS, FU, FV, LA, LM, or PC. The deliberate redundancy prevents one economic concept from being relabeled as another.

Return convention (v0.2)

Cache-backed fetches return a small head/tail preview, row count, date coverage, units, binding caveats, a provenance block, and an opaque artifact descriptor:

{
  "artifact": {
    "cache_key": "<64 lowercase hex characters>",
    "filename": "data.csv",
    "mime_type": "text/csv",
    "sha256": "<payload digest>",
    "byte_count": 1234
  }
}

full_data_path and manifest_path are deliberately absent from cache-backed responses. The SQLite row is the cache artifact; fiscus does not create a per-request file forest or a temporary materialization tree. The descriptor is duplicated only where useful: its identity and integrity fields also remain in the provenance block.

Python callers can obtain full content without relying on a path:

from pathlib import Path
from fiscus import FiscusService

with FiscusService() as fiscus:
    result = fiscus.get_series("fred.wdtgal", start="2024-01-01")
    key = result["artifact"]["cache_key"]

    payload = fiscus.read_bytes(key)                  # exact bytes
    rows = list(fiscus.iter_csv_rows(key))            # canonical CSV only
    receipt = fiscus.export_artifact(key, Path("wdtgal.csv"))

read_bytes, iter_csv_rows, provenance, and cache export accept either the full key or a unique hexadecimal prefix of at least 12 characters. iter_csv_rows rejects non-CSV artifacts instead of guessing how to parse a workbook or archive.

Expected failures have stable Python/CLI codes. In particular, HTTP 404/410 is source_removed, HTTP 403/451 is source_access_denied, and a statically declared nonmachine route is browser_download_only. A transient access denial is not silently promoted into a permanent catalog fact.

Cache lifetime versus caller-owned files

The cache defaults to the platform's device-local cache directory and can be relocated with FISCUS_DATA_DIR. Its quiescent cache/v2 surface is one fiscus.sqlite3 file; payloads, manifests, and latest pointers are rows in that database. SQLite uses rollback-journal DELETE mode, so a journal may exist during a write but no persistent WAL/SHM sidecars or artifact directories remain at rest.

The cache is durable across fiscus processes but is still a cache: operating-system cleanup, an explicit user deletion, or a replaced device can remove it. cache export / export_artifact creates a caller-owned file at the requested destination when archival or handoff durability matters. Conversely, a local_file catalog entry already points to caller-owned content, so its response keeps the real in-place full_data_path and manifest_path: null and never enters SQLite.

--refresh bypasses the latest pointer and re-reads the source. Current FRED responses use HTTP validators or retrieval UTC as immutable identity; their default real-time dates remain metadata. Historical FRED requests use alfred-as-of:DATE, and the date also enters canonical request parameters. Bytes already stored under one dataset/canonical-params/vintage identity are never mutated.

Mutable latest requests are re-fetched after 24 hours rather than serving an indefinitely stale cache entry. Explicit ALFRED information dates, SOMA as-of dates, and static release files retain their immutable-cache behavior. Z.1 series cache hits must match the package vintage currently selected. Cache exports must target a path outside the cache directory to protect its database and packages.

Exact date bounds on the deprecated BEA get-series alias produce a bounded CSV artifact. Its provenance links the canonical year-wide source artifact and labels the inclusive date filter; the observation values are unchanged. FiscalData provenance preserves the provider's field labels, types, and formats. In particular, MSPD Table 3 monetary amounts are millions of dollars, while its rates are percent. CES payroll employment counts jobs, which can count a multiple jobholder more than once; it is not a count of employed people.

Legacy v1 migration

A legacy filesystem cache is migrated only by the finite, explicit command:

fiscus cache migrate-v1
# or
fiscus cache migrate-v1 --from /path/to/cache/v1

Migration reads v1 without deleting or rewriting it, inserts valid artifacts directly into SQLite, preserves each usable authoritative latest.json pointer, and reports path-specific diagnostics for corrupt or incomplete legacy artifacts. It never materializes cache-owned files and does not enable dual-write.

Catalog overlays

Set FISCUS_EXTRA_CATALOG to one or more YAML files or directories separated by the operating-system path separator. Overlay entries merge by id; mapping fields merge recursively and lists replace. New entries must be complete after merging.

FISCUS_EXTRA_CATALOG=./local-catalog uv run fiscus catalog lint

See catalog/SCHEMA.md and catalog/schema.json.

Development

uv sync --frozen --group dev
uv run fiscus catalog lint
uv run pytest
uv run ruff check .

The unit suite is offline-first and uses tiny recorded response fixtures. A separate weekly workflow makes one cheap live request for each implemented family and opens or updates a single issue if a source fails.

Status

This is an alpha, solo-maintained public-data utility. Source endpoints can drift; catalog entries carry verified_on dates, and the project makes no support or uptime promise.

Available Tools

9 tools
bea_nipa_tableA

Fetch a complete BEA NIPA table for an explicit inclusive year range.

    table_id is BEA's canonical TableName (for example T10106). frequency must be
    A, Q, or M and must be advertised for that table in BEA's source inventory.
    The route is NIPA-only, sends an explicit Year list rather than Year=X, and
    returns source-observed metric labels plus per-line coverage. Uncurated tables
    omit reviewed units, history, and verified_on claims; exact curated pairs add
    a separate catalog overlay. BEA_API_KEY is required for a source retrieval.
    

Inputs: end_year (required), table_id (required), frequency (required), start_year (required), +1 more. Returns: object

find_seriesA

Search the curated catalog. Call this before guessing any series or dataset id.

    Curated results include units, history start, access needs, supported fetch tool,
    and caveat count so the next call can select the right concept. When the catalog has
    no match, uncurated candidates from the source's own search are returned under
    uncurated_upstream. BEA inventory candidates intentionally omit reviewed history,
    units, and verified_on. For keyless discovery across the Z.1 package data dictionary,
    pass family="z1".
    

Inputs: query (required), limit, family. Returns: object

fiscaldata_queryC

Query a curated Treasury FiscalData dataset selected from find_series.

    Use official FiscalData query keys such as fields, filter, sort, and page[size].
    Narrow large requests with a filter instead of raising max_pages indiscriminately.
    

Inputs: dataset_id (required), params, refresh, max_pages. Returns: object

get_fileA

Download a curated file artifact selected from find_series.

    Serves sources published as direct files (workbooks, delimited text, archives).
    Parseable csv/tsv files return a row preview; binary formats return provenance and
    an artifact descriptor. Read exact bytes at fiscus-cache://artifact/<cache_key>.
    

Inputs: dataset_id (required), refresh. Returns: object

get_seriesA

Fetch a cataloged series (FRED, BEA, BLS, OFR, NY Fed, TreasuryDirect families).

    Prefer ids from find_series. Uncataloged FRED and BLS series are also served as
    fred.<SERIES_ID> / bls.<SERIES_ID>. Their source unit metadata is labeled when
    available; otherwise annualization is explicitly unknown. These passthroughs carry
    interpretation warnings instead of curated review. Returns a compact preview,
    binding caveats, provenance, and an artifact descriptor. Read full bytes through
    fiscus-cache://artifact/<cache_key>. Set refresh only for a new source retrieval.
    For a FRED/ALFRED snapshot, set vintage_as_of to a closed past ISO date; start and
    end remain observation-date bounds, and FRED_API_KEY is required. Vintage failures
    distinguish an unset key, a rejected credential, no ALFRED history, a request before
    the first ALFRED vintage, and a source identifier that does not exist. A failed BOGZ1
    identifier is not auto-corrected because its two-letter prefix encodes the concept.
    

Inputs: dataset_id (required), end, start, refresh, +1 more. Returns: object

provenanceA

Re-emit the provenance manifest for any prior fetch by its cache key.

The cache key appears in every fetch response's artifact and provenance blocks; a unique hex prefix of at least 12 characters is accepted. Resolves only immutable artifacts, never a mutable "latest" pointer.

Inputs: cache_key (required). Returns: object

soma_holdingsA

Fetch CUSIP-level SOMA Treasury holdings for a weekly as-of snapshot date.

Omit asof for the latest published snapshot; the resolved date becomes part of the immutable cache identity. Snapshots begin July 2003 and are weekly, not daily.

Inputs: asof, cusip, refresh. Returns: object

source_caveatsA

Return every catalog caveat and whether it binds to the supplied context.

    Supply a date range to evaluate history seams and unit_classes when checking a planned
    combination of differently scaled, adjusted, or annualized series.
    

Inputs: dataset_id (required), end, start, params, +1 more. Returns: object

z1_seriesA

Fetch a Z.1 Financial Accounts series with enforced official prefix semantics.

kind must match the series prefix. This includes FR revaluations and the other official FA/FC/FG/FI/FL/FS/FU/FV/LA/LM/PC types. The call refuses to present one kind as another. Accepts bare mnemonics, .Q/.A suffixes, and FRED-style BOGZ1 aliases. If an official mnemonic is refused or absent, follow the server issue-reporting instruction before bypassing Fiscus.

Inputs: code (required), kind (required), end, start, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct data source or operation: provenance for cache keys, source_caveats for context binding, find_series for search, get_series for general fetch, and specific tools for BEA NIPA, FiscalData, file downloads, Z.1 series, and SOMA holdings. No two tools have overlapping purposes.

    Naming Consistency3/5

    Tool names use lowercase with underscores, but conventions vary: some are verb_noun (find_series, get_series, get_file), some are noun_noun (bea_nipa_table, fiscaldata_query, z1_series, soma_holdings), and 'provenance' is a single noun. This mix of verb-first and noun-first patterns reduces predictability.

    Tool Count5/5

    With 9 tools covering search, general fetch, specific data sources, file download, and metadata retrieval, the count is well-scoped for an economic data server. No tools feel redundant or missing.

    Completeness4/5

    The tool set covers core operations: search, fetch for multiple families (FRED, BEA, BLS, OFR, NY Fed, TreasuryDirect), specific endpoints for NIPA, FiscalData, Z.1, and SOMA, plus provenance and caveats. Minor gaps include no explicit tool for listing all available families, but find_series and get_series cover most needs.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Economic data MCP server that connects FRED, BLS, BEA, IMF, World Bank, and ECB to any MCP-compatible client, with built-in methodology rules to guide LLMs in selecting appropriate economic indicators.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server providing official US economic data including CPI inflation, famous prices, national debt, and Treasury interest rates. Enables AI agents to query historical and latest economic statistics via natural language.
      8
      40 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server serving official statistics from major data agencies (Statistics Canada, FRED, BLS, World Bank, etc.) as tools with provenance and verification, enabling search, retrieval, analysis, and monitoring via natural language.
      11
      58 npm
      MIT