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. Every fetch is catalog-selected, cached, labeled with units and known footguns, and stored 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 fiscus

For a one-off invocation without installation:

uvx fiscus find-series "Treasury General Account"

Zero-key quickstart

FRED public CSV and Treasury FiscalData work without credentials.

uvx fiscus find-series "TGA Wednesday level"
uvx fiscus get-series fred.wdtgal --start 2024-01-01
uvx 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, 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.

MCP server

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

uvx --from fiscus fiscus-mcp

Generic client configuration:

{
  "mcpServers": {
    "fiscus": {
      "command": "uvx",
      "args": ["--from", "fiscus", "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 eight 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]
fiscus fiscaldata-query DATASET_ID [--param KEY=VALUE] [--max-pages N]
fiscus get-file DATASET_ID
fiscus z1-series CODE {FL|FU|LM} [--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 FRED requests derive units, seasonal adjustment, annualization, and a conservative unit_class from official series metadata. 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. 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.

• 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 refuses to present a level (FL), transaction flow (FU), or market-value level (LM) as one another; 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.

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.

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. The response is stored under the source vintage reported by FRED or HTTP metadata, with retrieval UTC as a fallback; bytes already stored under one dataset/canonical-params/vintage identity are never mutated.

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.