Treasury Fiscaldata Mcp Server

io.github.cyanheads由 GitHub 账号 cyanheads 发布v0.5.0更新于 Nov 16, 2026

通过MCP查询美国国债、利率、汇率和财政数据集。

AI 翻译由 AI 模型根据下方的原文描述翻译,可能有误。

原文描述

Query US Treasury national debt, interest rates, exchange rates, and fiscal datasets via MCP.

已验证Streamable HTTP可网页运行金融数据与分析

概览

Treasury Fiscaldata 的托管 MCP 服务(treasury-fiscaldata.caseyjhand.com);无需登录;Streamable HTTP;7 个工具。

暂无 AI 概览:以下信息来自注册中心条目和服务本身。

端点
treasury-fiscaldata.caseyjhand.com
最近检查

安装

在 SourceWeft 中

  1. 打开 控制台中的 Treasury Fiscaldata Mcp Server,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.cyanheads%2Ftreasury-fiscaldata-mcp-server/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "treasury-fiscaldata": {
      "type": "http",
      "url": "https://treasury-fiscaldata.caseyjhand.com/mcp"
    }
  }
}

README

@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

ToolDescription
treasury_list_datasetsBrowse the curated catalog of 17 Treasury Fiscal Data endpoints with field names, descriptions, and update cadence
treasury_query_datasetQuery any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page — with optional DataCanvas spill
treasury_get_debtFetch national debt (Debt to the Penny) — latest record, specific date, or date-range series with optional DataCanvas spill
treasury_get_interest_ratesAverage interest rates Treasury pays on outstanding securities by type — marketable issues, non-marketable series, and aggregate totals
treasury_get_exchange_ratesOfficial Treasury statutory exchange rates for ~165 countries, published quarterly
treasury_dataframe_describeList DataCanvas dataframes materialized by the treasury_* tools with schema, row count, and TTL
treasury_dataframe_queryRun a single-statement SELECT against DataCanvas dataframes using standard DuckDB SQL
treasury_dataframe_dropDelete a staged dataframe and its provenance (disabled unless TREASURY_DATAFRAME_DROP_ENABLED=true)

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:

sh
claude mcp add --transport http treasury-fiscaldata-mcp-server https://treasury-fiscaldata.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add treasury-fiscaldata-mcp-server -- npx -y @cyanheads/treasury-fiscaldata-mcp-server

For other MCP clients:

json
{  "mcpServers": {    "treasury-fiscaldata-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/treasury-fiscaldata-mcp-server"]    }  }}

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

VariableDescriptionDefault
CANVAS_PROVIDER_TYPEduckdb backs dataframe describe/query, and drop when enabled. With none, callable canvas tools return canvas_unavailable; drop stays off the tool list unless separately enabled.duckdb (none in the desktop bundle)
CANVAS_TTL_MSLifetime of each staged DataCanvas dataframe in milliseconds, fixed at staging. Also the shared canvas's idle TTL, so startup fails when it exceeds CANVAS_ABSOLUTE_CAP_MS (default 7 days).86400000 (24h)
TREASURY_DATAFRAME_DROP_ENABLEDRegister treasury_dataframe_drop as callable. Also requires CANVAS_PROVIDER_TYPE=duckdb.false
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_SESSION_MODEHTTP session handling: auto, stateful, or stateless. Setting it overrides the server's own declaration; leaving it unset falls through to that declaration, not to the schema default.stateless (declared in src/index.ts)
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, notice, warning, error).info
LOGS_DIRDirectory for log files (Node.js/Bun only). A relative path resolves against the server's own package directory.<package-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog failed-call arguments and results, redacted by key name. Secrets inside free-form values are not redacted.false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTESByte cap for each logged failed-call payload.16384
OTEL_ENABLEDEnable OpenTelemetry spans and metrics.false
OTEL_EXPORTER_OTLP_ENDPOINTBase OTLP endpoint for traces and metrics.Unset
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTExplicit OTLP log endpoint; the base endpoint does not enable log export.Unset

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+.

sh
git clone https://github.com/cyanheads/treasury-fiscaldata-mcp-server.gitcd treasury-fiscaldata-mcp-server && bun installcp .env.example .env
  • Build and run:

    sh
    bun run rebuild
    bun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck         # Lint, format, typecheck, securitybun run test             # Vitest test suitebun run lint:mcp         # Validate MCP definitions against specbun run lint:deps        # Detect unused and missing dependencies with Knipbun run verify:catalog   # Probe every catalog endpoint and field against the live API

    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

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/treasury-fiscaldata-mcp-server:latest

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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/config/Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools/definitions/Tool definitions (*.tool.ts) — 5 data tools + 3 DataCanvas tools, including opt-in drop.
src/mcp-server/tools/markdown-encoding.tsEncoders that keep table cells, code spans, and notices intact through a Markdown parse.
src/mcp-server/tools/endpoint-fetcher.tsThe per-call request function the three convenience tools send every request through: one fetch budget, their own rejection reasons, and a check that each answer still lists the fields they read.
src/services/fiscal-data/Treasury Fiscal Data API client, embedded endpoint catalog, and types.
src/services/canvas-bridge/Adapter over the framework DataCanvas: one shared canvas per tenant, df_<id> minting, fixed per-table expiry, register_as catalog-name refusal.
tests/Unit and integration tests mirroring src/.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

来源:README.md,提交 a6c97c4

工具

7

treasury_list_datasets

List Treasury Fiscal Data Datasets

Browse the curated catalog of US Treasury Fiscal Data API endpoints. Returns endpoint paths, field names, descriptions, and update cadence for each dataset. Use this tool before treasury_query_dataset to discover the correct endpoint path and field names. The catalog is a curated subset of the full API — pass any endpoint path directly to treasury_query_dataset to query datasets not listed here; a field name the endpoint lacks fails with an error that lists every field it has. The catalog covers debt, interest rates, exchange rates, revenue/spending, savings bonds, and securities datasets.

输入参数searchcategory

treasury_query_dataset

Query Treasury Fiscal Data Dataset

Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page. Call treasury_list_datasets first to get the correct endpoint path and exact field names; a field name the endpoint lacks fails with an error listing every field it has. Filter syntax: each condition is { field, operator, value } where operator is eq/gt/gte/lt/lte/in (e.g., record_date:gte:2024-01-01). Multiple conditions are ANDed together. All response values are strings per the API contract, including numbers and dates; "null" (string) means no value. Supply canvas_id to stage the page result as a DataCanvas table — read its column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query (requires CANVAS_PROVIDER_TYPE=duckdb on the server).

输入参数sortfieldsfiltersendpoint必填canvas_idpage_sizepage_number

treasury_get_debt

Get National Debt

Fetch national debt (Debt to the Penny) — total public debt outstanding broken into publicly-held debt and intragovernmental holdings. Three modes: "latest" returns the most recent business day's record; "date" returns the record for a specific date (must be a business day — the API only records debt on days markets are open); "series" returns a date range, staging the full result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query. Records go back to 1993-04-01.

输入参数datemodeend_datecanvas_idstart_date

treasury_get_interest_rates

Get Treasury Interest Rates

Average interest rates Treasury pays on its outstanding securities by security type. Answers "what is the government's cost of borrowing?" Covers every type Treasury reports — marketable issues, non-marketable series, and the aggregate totals — and which types it reports changes over the years, so omit security_type to see the ones a given period carries. Rates are percentages, not basis points. Updated monthly (end-of-month records). Mode "latest" returns the most recent month's rates for all or one security type; "series" returns a time history, staging the result as a DataCanvas table when canvas_id is set or the range matches more than 200 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query.

输入参数modeend_datecanvas_idstart_datesecurity_type

treasury_get_exchange_rates

Get Treasury Exchange Rates

Official Treasury reporting exchange rates for ~165 countries — the rates US federal agencies are required to use when converting foreign currency to USD for official reporting. Published quarterly (March 31, June 30, Sep 30, Dec 31); mode "latest" returns the most recently published quarter. Rate is expressed as foreign currency units per 1 USD (e.g., a Japan-Yen rate of 159.41 means 1 USD = 159.41 JPY). These are NOT market exchange rates and are not suitable for financial transaction pricing. Mode "series" stages the result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query.

输入参数modeend_datecanvas_idcountriesstart_date

treasury_dataframe_describe

Describe Treasury Dataframes

List DataCanvas dataframes materialized by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, and column schema. Use this tool before treasury_dataframe_query to discover table names and column types. Requires CANVAS_PROVIDER_TYPE=duckdb.

输入参数name

treasury_dataframe_query

Query Treasury Dataframes

Run a single-statement SELECT against DataCanvas dataframes registered by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer. Tables staged from Treasury API rows hold every column as VARCHAR — CAST to DECIMAL or DATE for arithmetic and date comparisons; a register_as table keeps the column types its SELECT produced. Use treasury_dataframe_describe to list available table names and column schemas before querying.

输入参数sql必填previewrow_limitregister_as

版本历史

6
  1. v0.5.0最新Nov 16, 2026
  2. v0.4.0Oct 29, 2026
  3. v0.3.0Oct 25, 2026
  4. v0.2.0Oct 4, 2026
  5. v0.1.11Sep 21, 2026
  6. v0.1.10Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分