@cyanheads/treasury-fiscaldata-mcp-server
Query US Treasury national debt, interest rates, exchange rates, and fiscal datasets via MCP.
8 Tools · dataframe drop is opt-in
Overview
US Treasury Fiscal Data: the national debt, interest rates, exchange rates, and other federal fiscal datasets. Pull the headline numbers in one call, query any Fiscal Data endpoint directly, and run SQL over large pulls.
Tools
Capability reference
treasury_list_datasets tool
- Filter by category (
debt, interest_rates, exchange_rates, revenue_spending, savings_bonds, securities, other) or keyword search.
- Returns endpoint paths, fields, types, and update cadence from a bundled catalog, with no network call.
treasury_query_dataset tool
- Query an endpoint with
{ field, operator, value } filters (eq, gt, gte, lt, lte, in), sort, and pagination: page_size 1–10000 (default 100), page_number starts at 1.
- Returns rows, field labels,
total_count, and total_pages; a fields selection returns distinct rows, and the counts count those. Error reasons are invalid_endpoint, invalid_field, invalid_filter, sort_field_not_selected, and page_out_of_range.
- Pass
canvas_id to stage the page for SQL analysis; the returned canvas_id is the assigned table name.
treasury_get_debt tool
mode=latest returns the newest business-day record; mode=date accepts a YYYY-MM-DD date; mode=series accepts a date range. Coverage begins 1993-04-01.
- Returns debt totals and a 20-row series preview; compare
retrieved_records with total_records. A missing date returns no_data_for_date.
- Series staging starts above 500 rows or on request via
canvas_id; paging stops at 50,000 rows.
treasury_get_interest_rates tool
mode=latest returns the newest month's rates, optionally filtered by security_type; mode=series accepts a date range.
- Rates are percentages, with available security types disclosed when a filter matches nothing; the series preview holds at most 20 rows.
- Series staging starts above 200 rows or on request via
canvas_id.
treasury_get_exchange_rates tool
- Quarterly official reporting rates in foreign currency units per 1 USD. Filter
countries by exact name; mode=latest returns one current row per currency and mode=series accepts a date range.
- Each row carries
record_date and effective_date; mixed_record_dates flags a result spanning quarters. Series previews hold 20 rows; retrieved_records discloses progress against total_records.
- Series staging starts above 500 rows or on request via
canvas_id; paging stops at 50,000 rows.
country_not_found error when a requested country has no records
treasury_dataframe_describe tool
- Omit
name to list the tenant's active dataframes, or supply one exact table name.
- Returns provenance, created/expiry timestamps, row count, and column schema;
truncated / max_rows disclose a capped source pull.
- Table expiry defaults to 24h after staging, configurable with
CANVAS_TTL_MS. Queries do not extend it, and a server restart or the shared canvas reaching its maximum lifetime (CANVAS_ABSOLUTE_CAP_MS, default 7 days) can remove a table sooner; describe lists only tables still on the canvas.
treasury_dataframe_query tool
- Accepts one read-only SELECT;
row_limit defaults to 1000 (max 10000) and preview may not exceed it. System catalogs, external-file functions, and SQL mutations are denied.
- Returns rows and
row_count_capped; errors distinguish canvas_unavailable, system_catalog_access, invalid_sql, missing_table, and invalid_query_bounds.
register_as materializes the full result as a new dataframe with a fresh TTL. A name the system-catalog deny would refuse in SQL (duckdb_tables, pg_class, …) is refused with system_catalog_access before anything is staged.
treasury_dataframe_drop tool
- Accepts the exact
name from treasury_dataframe_describe, a data tool's canvas_id, or query's registered_as; deletes that table and its provenance for the tenant.
- Returns
name and dropped: true; an absent or expired table returns missing_table with guidance to list active tables.
- Disabled by default. Set
TREASURY_DATAFRAME_DROP_ENABLED=true and CANVAS_PROVIDER_TYPE=duckdb to make it callable; the HTTP landing page shows the disabled tool and enable hint otherwise.
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Fiscal Data-specific:
- All API values are strings;
"null" means no value. Columns staged from Treasury API rows are VARCHAR — CAST to DECIMAL or DATE for arithmetic and date comparisons; a register_as table keeps the types its SELECT produced. DataCanvas requires CANVAS_PROVIDER_TYPE=duckdb; configured canvas tools report canvas_unavailable otherwise.
- A filter value cannot contain a comma — the API reads one as the start of another condition — so every tool refuses it as
invalid_filter before sending. The three convenience tools report upstream_schema_changed when the API renames or drops a field they read.
- Curated catalog of 17 endpoints with field metadata — no discovery round-trip required; pass any endpoint path directly to
treasury_query_dataset for datasets outside the catalog
- Convenience tools for the three most-queried datasets — national debt, interest rates, exchange rates
- DataCanvas integration: large pulls register as
df_<id> dataframes queryable via DuckDB SQL, with automatic staging thresholds per tool
- No API key required — the US Treasury Fiscal Data API is free and public
Agent-friendly output:
- Provenance: filter-expression echo (
applied_filters) and field-label maps (field_labels) let agents verify what was sent and read raw field names
- Enrichment notices: empty-result guidance, partial-country mismatches, canvas staging confirmations, and truncated-series warnings all name the next tool call
- Graceful truncation: series and query results carry
truncated / retrieved_records / row_count_capped fields instead of silently dropping rows
- Canvas provenance: source tool, original query parameters, row count, and column schema surfaced by
treasury_dataframe_describe
Getting started
Connect Claude Code to the public instance:
Or run it locally:
For other MCP clients:
No API key is required. DataCanvas is enabled by default in npm and Docker installs; CANVAS_PROVIDER_TYPE=none disables it. The portable Claude Desktop .mcpb bundle omits DuckDB native bindings and supports Treasury API queries with DataCanvas disabled. For Docker or a source build, see Running the server.
Configuration
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher to build; the installed server also runs on Node.js v24+.
-
Build and run:
-
Run checks and tests:
verify:catalog makes live Fiscal Data requests and runs separately from devcheck and the test suite. Run it after editing src/services/fiscal-data/datasets.ts and before a release.
Builds type-check and emit declarations with TypeScript, then use Bun to bundle server code as Node-compatible ESM in dist/index.js. Package dependencies remain external, including the framework and DuckDB native bindings. The installed server runs on Node or Bun; building from source requires Bun. Dependency checks use knip.jsonc to cover source, scripts, and tests.
Docker
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/treasury-fiscaldata-mcp-server. A native build-host dependency stage cross-installs DuckDB bindings for the target architecture, preserves the release-age and security checks, and removes unused musl bindings. OpenTelemetry peers are installed at the framework's declared ranges — build with --build-arg OTEL_ENABLED=false to omit them.
To build locally, run docker build -t treasury-fiscaldata-mcp-server .. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/treasury-fiscaldata-mcp-server:latest as the MCP client's launch command.
DataCanvas SQL workflow
Use the hosted endpoint, npm, or Docker for dataframe staging and SQL. Pass canvas_id to a data tool to stage its results, then use the returned minted df_<id> table identifier with treasury_dataframe_describe and treasury_dataframe_query. Treasury columns are VARCHAR: cast numeric and date columns before arithmetic, comparisons, or date operations. The input canvas_id enables staging; it does not name the output table.
Project structure
Development guide
See CLAUDE.md and AGENTS.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catch in tool logic
- Use
ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
- All Treasury API values are strings — validate and CAST in downstream SQL; never fabricate missing fields
- Register new tools via the arrays in
src/index.ts
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.