treasury-fiscaldata-mcp-server

<div align="center">
  <h1>@cyanheads/treasury-fiscaldata-mcp-server</h1>
  <p><b>Query US Treasury national debt, interest rates, exchange rates, and fiscal datasets via MCP.</b>
  <div>7 Tools</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.10-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/treasury-fiscaldata-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/treasury-fiscaldata-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/treasury-fiscaldata-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/treasury-fiscaldata-mcp-server/releases/latest/download/treasury-fiscaldata-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=treasury-fiscaldata-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdHJlYXN1cnktZmlzY2FsZGF0YS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22treasury-fiscaldata-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ftreasury-fiscaldata-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://treasury-fiscaldata.caseyjhand.com/mcp](https://treasury-fiscaldata.caseyjhand.com/mcp)

</div>

---

## Tools

Five tools for querying the US Treasury Fiscal Data API, plus two for SQL analytics over DuckDB-backed DataCanvas dataframes:

| Tool | Description |
|:-----|:------------|
| `treasury_list_datasets` | Browse the curated catalog of 17 Treasury Fiscal Data endpoints with field names, descriptions, and update cadence |
| `treasury_query_dataset` | Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page — with optional DataCanvas spill |
| `treasury_get_debt` | Fetch national debt (Debt to the Penny) — latest record, specific date, or date-range series with optional DataCanvas spill |
| `treasury_get_interest_rates` | Average interest rates Treasury pays on outstanding securities by type — marketable issues, non-marketable series, and aggregate totals |
| `treasury_get_exchange_rates` | Official Treasury statutory exchange rates for ~165 countries, published quarterly |
| `treasury_dataframe_describe` | List DataCanvas dataframes materialized by the treasury_* tools with schema, row count, and TTL |
| `treasury_dataframe_query` | Run a single-statement SELECT against DataCanvas dataframes using standard DuckDB SQL |

### `treasury_list_datasets`

Browse the embedded catalog of available Treasury Fiscal Data endpoints. No network calls — serves from a static catalog bundled with the server.

- Filter by category: `debt`, `interest_rates`, `exchange_rates`, `revenue_spending`, `savings_bonds`, `securities`, `other`
- Keyword search against dataset name and description (case-insensitive substring)
- Returns endpoint paths, field names, types, and update cadence
- Use this first to get the exact endpoint path and field names before calling `treasury_query_dataset`
- Every path and field name is checked against the live API by `bun run verify:catalog`, so a dataset Treasury moves or renames fails a gate rather than reaching a caller

---

### `treasury_query_dataset`

Generic parameterized query against any Treasury Fiscal Data endpoint.

- Filter syntax: `{ field, operator, value }` where operator is `eq`, `gt`, `gte`, `lt`, `lte`, `in`
- Multiple filters ANDed together
- Pagination via `page_size` (1–10000) and `page_number`
- Sort by any field, descending with `-` prefix (e.g. `-record_date`)
- All response values are strings per the API contract — including numeric and date fields; `"null"` means no value
- Pass `canvas_id` to stage the page as a DataCanvas table — the server assigns the name and returns it in `canvas_id`; read its schema with `treasury_dataframe_describe`, then SQL it with `treasury_dataframe_query` (requires `CANVAS_PROVIDER_TYPE=duckdb`)

---

### `treasury_get_debt`

Convenience tool for national debt (Debt to the Penny) — total public debt outstanding broken into publicly-held debt and intragovernmental holdings.

- `mode=latest` — most recent business-day record
- `mode=date` — specific business day (YYYY-MM-DD; API only records debt on market-open days)
- `mode=series` — date range, sorted newest-first; auto-spills to DataCanvas when the series exceeds 500 rows
- Records go back to 1993-04-01

---

### `treasury_get_interest_rates`

Average interest rates the Treasury pays on outstanding securities. Updated monthly (end-of-month records).

- Covers every security type Treasury reports — marketable issues, non-marketable series, and aggregate totals
- `security_type` takes any `security_desc` value the data carries, matched exactly; which types Treasury publishes changes over the years, so when a filter matches nothing the response names the types the data does hold
- `mode=latest` — most recent month's rates for all or one security type
- `mode=series` — time-range history; auto-spills to DataCanvas when results exceed 200 rows

---

### `treasury_get_exchange_rates`

Official Treasury statutory reporting exchange rates for ~165 countries, published quarterly (March 31, June 30, Sep 30, Dec 31).

- Rate expressed as foreign currency units per 1 USD (a Japan-Yen rate of 159.41 means 1 USD = 159.41 JPY)
- These are **not** market exchange rates — required by US federal agencies for foreign-currency-to-USD conversions in official reporting
- Filter to one or more countries by exact name; omit for every country in a quarter
- `mode=latest` returns one row per currency — the operative rate, newest `record_date` and then newest `effective_date`, so an amended rate supersedes the one it replaced and a country holding two legal tenders keeps both
- Treasury amends a published quarter by reissuing a rate under the same `record_date` with a later `effective_date`, so both dates ride every row; `mixed_record_dates` flags a result whose rows are not all from one quarter
- `mode=series` auto-spills to DataCanvas when results exceed 500 rows (~19,000 rows full history, back to 2001-03-31)

---

### `treasury_dataframe_describe` / `treasury_dataframe_query`

In-conversation SQL analytics over the dataframes that `treasury_query_dataset`, `treasury_get_debt`, `treasury_get_interest_rates`, and `treasury_get_exchange_rates` materialize on a shared DuckDB-backed DataCanvas. Each data-returning call with `canvas_id` adds a `df_XXXXX_XXXXX` handle; read its columns with `treasury_dataframe_describe`, then pass the handle to `treasury_dataframe_query` for joins, aggregates, window functions, and CTEs — standard DuckDB SQL.

- **Read-only.** Writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the SQL gate. System catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) are denied at the bridge layer.
- **All Treasury columns are VARCHAR.** CAST to `DECIMAL` or `DATE` for arithmetic and date comparisons.
- **`register_as` chaining.** `treasury_dataframe_query` can persist its result as a new dataframe with a fresh TTL for multi-step analysis.
- **Per-table TTL.** Dataframes age on their own clock (default 24h, override with `CANVAS_TTL_MS`).
- Requires `CANVAS_PROVIDER_TYPE=duckdb`.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool definitions — single file per tool, framework handles registration and validation
- Structured output schemas with automatic formatting for human-readable display
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth: `none`, `jwt`, `oauth`
- Structured logging with request-scoped context
- STDIO and Streamable HTTP transports

Treasury-specific:

- Curated catalog of 17 Treasury Fiscal Data endpoints with field metadata — no discovery round-trip required. Pass any endpoint path directly to `treasury_query_dataset` to access datasets not in the catalog.
- Convenience tools for the three most-queried datasets (national debt, interest rates, exchange rates)
- Full generic access to any Fiscal Data endpoint via `treasury_query_dataset`
- DataCanvas integration: large time-series pulls register as `df_<id>` dataframes queryable via DuckDB SQL
- No API keys required — the US Treasury Fiscal Data API is free and public

Agent-friendly output:

- Filter expression echo (`applied_filters`) so agents can verify what was sent to the API
- Field-label maps on query results (`field_labels`) map raw field names to human-readable labels
- Enrichment notices on empty results, partial-country mismatches, staged canvas tables, and truncated series guide the next tool call
- Canvas provenance: source tool, original query parameters, row count, and column schema surfaced by `treasury_dataframe_describe