fiscus
fiscus is an MCP server for discovering, fetching, and auditing curated US economic data with provenance and caveats.
Search the curated catalog and upstream source candidates (FRED, BEA, Z.1) with
find_series.Fetch cataloged or passthrough FRED/BLS series, plus BEA, OFR, NY Fed, and TreasuryDirect families, via
get_series.Query Treasury FiscalData datasets with official query parameters and pagination controls.
Fetch complete BEA NIPA tables by frequency and explicit inclusive year range.
Fetch Z.1 Financial Accounts series with enforced official prefix semantics.
Fetch CUSIP-level SOMA Treasury holdings for weekly as-of snapshots.
Download curated file artifacts such as workbooks, delimited text, and archives.
Read exact cached payload bytes through the read-only
fiscus-cache://artifact/{cache_key}resource.Inspect catalog caveats and whether they bind to a given date range or unit classes.
Re-emit immutable provenance manifests for prior fetches by cache key or unique prefix.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fiscus find the TGA Wednesday level series"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.gitFor 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 2Set 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-mcpGeneric 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 mcpCall 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 conservativeunit_classfrom 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 CSVfootnotescolumn. Every passthrough remains marked "uncataloged — no curated caveat review." The catalog is for caveats, not coverage.Upstream search fallback: when
find-serieshas no complete catalog match, it appends candidates from FRED's own search (requiresFRED_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 z1searches the current official package data dictionary without a key and returns the exactz1-series CODE KINDcall for uncataloged matches.BEA NIPA table access:
find-series QUERY --family beafalls 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-tablefixesdatasetname=NIPA, requires explicit inclusive years, and returns per-line observed coverage. Uncurated results and responses omit reviewed history, units, andverified_on; an exact cataloged table/frequency pair adds a separate curation overlay.get-series bea.nipa_t10106remains a deprecated one-release alias.Local artifacts: private overlay entries can register files already on disk via the
local_fileexecutor (endpoint.local_path) — served in place with a content-hash provenance block, never copied. Seecatalog/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/v1Migration 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 lintSee 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 toolsbea_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Query US Treasury national debt, interest rates, exchange rates, and fiscal datasets via MCP.
Macroeconomic and other official data from 170+ publishers, resolved from natural language with provenance.
MCP access to the U.S. federal procurement graph: contracts, opportunities, entities, and more.
Related MCP Servers
- 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
- AlicenseNot gradedqualityDmaintenanceEconomic 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
- AlicenseAqualityDmaintenanceMCP 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.840 npmMIT
- AlicenseAqualityDmaintenanceMCP 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.1158 npmMIT