treasury-fiscaldata-mcp-server

---

概述

美国财政部财政数据：国债、利率、汇率及其他联邦财政数据集。通过一次调用获取关键数据，直接查询任意财政数据端点，并对大量查询结果运行 SQL。

工具

工具	描述
treasury_list_datasets	浏览包含 17 个财政部财政数据端点的精选目录，查看字段名称、描述和更新频率
treasury_query_dataset	按路径、字段列表、筛选条件、排序方式和页码查询任意财政部财政数据端点——可选择将结果溢出到 DataCanvas
treasury_get_debt	获取国债数据（精确到每一分钱的债务）——最新记录、指定日期或日期范围序列，可选择将结果溢出到 DataCanvas
treasury_get_interest_rates	按类型查询财政部对未偿证券支付的平均利率——可交易发行、非可交易系列和汇总总额
treasury_get_exchange_rates	财政部官方法定汇率，涵盖约 165 个国家，每季度发布
treasury_dataframe_describe	列出 treasury_* 工具生成的 DataCanvas DataFrame，并显示架构、行数和 TTL
treasury_dataframe_query	使用标准 DuckDB SQL，对 DataCanvas DataFrame 执行单条 SELECT 语句
treasury_dataframe_drop	删除暂存的 DataFrame 及其来源记录（除非设置 TREASURY_DATAFRAME_DROP_ENABLED=true，否则默认禁用）

功能参考

treasury_list_datasets _工具

• 按类别（debt、interest_rates、exchange_rates、revenue_spending、savings_bonds、securities、other）筛选，或按关键词搜索。
• 从内置目录返回端点路径、字段、类型和更新频率，不会发起网络请求。

---

treasury_query_dataset _工具

• 使用 { field, operator, value } 筛选条件（eq、gt、gte、lt、lte、in）、排序和分页查询端点：page_size 为 1–10000（默认值为 100），page_number 从 1 开始。
• 返回行、字段标签、total_count 和 total_pages；错误原因包括 invalid_endpoint、invalid_field、invalid_filter 和 page_out_of_range。
• 传入 canvas_id，将当前页暂存以供 SQL 分析；返回的 canvas_id 即分配的表名。

---

treasury_get_debt _工具

• mode=latest 返回最新营业日的记录；mode=date 接受 YYYY-MM-DD 格式的日期；mode=series 接受日期范围。数据覆盖范围始于 1993-04-01。
• 返回债务总额和包含 20 行的系列预览；请对比 retrieved_records 和 total_records。若指定日期没有数据，则返回 no_data_for_date。
• 系列数据超过 500 行时会开始暂存，也可通过 canvas_id 请求暂存；分页最多可读取 50,000 行。

---

treasury_get_interest_rates _工具

• mode=latest 返回最新月份的利率，可选按 security_type 筛选；mode=series 接受日期范围。
• 利率以百分比表示；若筛选结果为空，会列出可用的证券类型；系列预览最多包含 20 行。
• 系列数据超过 200 行时会开始暂存，也可通过 canvas_id 请求暂存。

---

treasury_get_exchange_rates _工具

• 按季度发布的官方汇率，单位为每 1 USD 可兑换的外币单位数。countries 按国家或地区的精确名称筛选；mode=latest 返回每种货币的一条当前记录，mode=series 接受日期范围。
• 每行包含 record_date 和 effective_date；若结果跨越多个季度，mixed_record_dates 会标记这一情况。系列预览包含 20 行；retrieved_records 显示相对于 total_records 的读取进度。
• 系列数据超过 500 行时会开始暂存，也可通过 canvas_id 请求暂存；分页最多可读取 50,000 行。
• 请求的国家或地区没有记录时，会返回 country_not_found 错误。

---

treasury_dataframe_describe _工具

• 省略 name 可列出租户的活动数据框，或提供一个精确的表名。
• 返回数据来源、创建和过期时间戳、行数及列架构；truncated / max_rows 用于说明源数据提取是否达到上限。
• 表默认在暂存 24h 后过期，可通过 CANVAS_TTL_MS 配置。

---

treasury_dataframe_query _工具

• 接受一条只读 SELECT 语句；row_limit 默认为 1000（最大值为 10000），且 preview 不得超过此限制。系统目录、外部文件函数和 SQL 修改操作均被拒绝。
• 返回行和 row_count_capped；错误类型包括 canvas_unavailable、system_catalog_access、invalid_sql、missing_table 和 invalid_query_bounds。
• register_as 会将完整查询结果物化为新的数据框，并为其设置新的 TTL。

---

treasury_dataframe_drop _工具

• 接受 treasury_dataframe_describe 中的精确 name、数据工具的 canvas_id 或查询的 registered_as；删除该表及其在租户中的来源信息。
• 返回 name 和 dropped: true；若表不存在或已过期，则返回 missing_table，并提示列出活动表。
• 默认禁用。设置 TREASURY_DATAFRAME_DROP_ENABLED=true 和 CANVAS_PROVIDER_TYPE=duckdb 后即可调用；否则 HTTP 着陆页会显示此工具已禁用及启用提示。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Fiscal Data 专属功能：

• 所有 API 值均为字符串；"null" 表示无值。Treasury 数据框列为 VARCHAR — 执行算术运算和日期比较时，请 CAST 为 DECIMAL 或 DATE。DataCanvas 需要 CANVAS_PROVIDER_TYPE=duckdb；否则，已配置的画布工具会报告 canvas_unavailable。
• 精选目录包含 17 个端点及其字段元数据 — 无需往返查询来发现端点；对于目录之外的数据集，可将任意端点路径直接传给 treasury_query_dataset
• 为最常查询的三个数据集提供便捷工具 — 国债、利率、汇率
• DataCanvas 集成：大量拉取的数据会注册为可通过 DuckDB SQL 查询的 df_<id> 数据框，并为每种工具自动设置暂存阈值
• 无需 API 密钥 — 美国财政部 Fiscal Data API 免费开放

便于 Agent 使用的输出：

• 来源信息：筛选表达式回显（applied_filters）和字段标签映射（field_labels）让 Agent 能够核实已发送的内容并读取原始字段名
• 增强提示：空结果指导、国家部分不匹配提示、画布暂存确认和截断序列警告都会指出下一步要调用的工具
• 优雅截断：序列和查询结果会包含 truncated / retrieved_records / row_count_capped 字段，而不是静默丢弃行
• 画布来源信息：treasury_dataframe_describe 会显示来源工具、原始查询参数、行数和列架构

开始使用

公共托管实例

公共实例位于 https://treasury-fiscaldata.caseyjhand.com/mcp — 无需安装。该实例使用 Streamable HTTP；各客户端的配置格式各不相同。

对于 Claude Code：

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

对于 Cline（cline_mcp_settings.json）：

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

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "treasury-fiscaldata-mcp-server": {
      "url": "https://treasury-fiscaldata.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”中添加远程服务。

Claude Desktop 的 .mcpb 下载包支持 Treasury API 查询，但禁用了 DataCanvas。其便携包不包含 DuckDB 的平台专用原生绑定。若要暂存数据框并执行 SQL，请使用托管端点、npm 或 Docker。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "treasury-fiscaldata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/treasury-fiscaldata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "treasury-fiscaldata-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/treasury-fiscaldata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "treasury-fiscaldata-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/treasury-fiscaldata-mcp-server:latest"
      ]
    }
  }
}

若要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

DataCanvas SQL 工作流

对于大型时间序列拉取或多数据集分析，请使用 DataCanvas SQL 工作流：

1. 使用托管端点、npm 或 Docker。 默认启用 DataCanvas；CANVAS_PROVIDER_TYPE=none 可将其禁用。桌面 .mcpb 包不包含 DataCanvas。
2. 调用带有 canvas_id 的数据工具 — 例如，使用 mode=series 和 canvas_id 值调用 treasury_get_debt，或调用带有 canvas_id 的 treasury_query_dataset。该工具会将结果注册为 df_XXXXX_XXXXX 数据框，并返回表名。
3. 使用 treasury_dataframe_describe 检查架构 — 列出列名、类型（Treasury 数据的类型均为 VARCHAR）、行数和 TTL。
4. 通过 treasury_dataframe_query 使用 SQL 查询 — 使用 DuckDB 标准 SELECT，支持联接、聚合、窗口函数和 CTE。执行算术运算时，请将 VARCHAR 列 CAST 为 DECIMAL 或 DATE。

-- Example: debt trend over the last year, month-end records only
SELECT
  record_date,
  CAST(tot_pub_debt_out_amt AS DECIMAL) / 1e12 AS total_debt_trillions
FROM df_xxxxx
WHERE CAST(record_date AS DATE) >= CURRENT_DATE - INTERVAL 1 YEAR
ORDER BY record_date DESC

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — 美国财政部 Fiscal Data API 免费开放。
• npm 和 Docker 安装默认启用 DataCanvas SQL，其中包含 @duckdb/node-api 及其原生绑定。便携式桌面 .mcpb 包会禁用此功能。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/treasury-fiscaldata-mcp-server.git

2. 进入目录：

cd treasury-fiscaldata-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env as needed — no required vars; CANVAS_PROVIDER_TYPE=none disables SQL

配置

变量	描述	默认值
CANVAS_PROVIDER_TYPE	duckdb 支持 DataCanvas 数据帧的描述、查询，并在启用时支持删除。使用 none 时，可调用的 DataCanvas 工具会返回 canvas_unavailable；除非单独启用，否则删除工具不会列入工具列表。	duckdb（桌面应用包中为 none）
CANVAS_TTL_MS	DataCanvas 数据帧的每表 TTL，单位为毫秒。	86400000（24h）
TREASURY_DATAFRAME_DROP_ENABLED	将 treasury_dataframe_drop 注册为可调用工具。还需要设置 CANVAS_PROVIDER_TYPE=duckdb。	false
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话处理方式：auto、stateful 或 stateless。设置此项会覆盖服务自身的声明；不设置时会采用该声明，而非架构默认值。	stateless（在 src/index.ts 中声明）
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOGS_DIR	日志文件目录（仅 Node.js/Bun）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果，并按键名进行脱敏。自由格式值中的机密信息不会脱敏。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每个失败调用日志负载的字节数上限。	16384
OTEL_ENABLED	启用 OpenTelemetry 跟踪和指标。	false
OTEL_EXPORTER_OTLP_ENDPOINT	跟踪和指标的 OTLP 基础端点。	未设置
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	显式指定 OTLP 日志端点；基础端点不会启用日志导出。	未设置

完整的可选覆盖项列表，请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck         # Lint, format, typecheck, security
  bun run test             # Vitest test suite
  bun run lint:mcp         # Validate MCP definitions against spec
  bun run lint:deps        # Detect unused and missing dependencies with Knip
  bun run verify:catalog   # Probe every catalog endpoint and field against the live API
  

  verify:catalog 会向 Fiscal Data 发起实时请求，并独立于 devcheck 和测试套件运行。编辑 src/services/fiscal-data/datasets.ts 后、发布前，请运行此命令。

  构建过程会使用 TypeScript 进行类型检查并生成声明文件，然后使用 Bun 将服务端代码打包为兼容 Node 的 ESM 文件 dist/index.js。包括框架和 DuckDB 原生绑定在内的依赖包会保持外部依赖。已安装的服务可在 Node 或 Bun 上运行；从源代码构建则需要 Bun。依赖项检查使用 knip.jsonc 覆盖源代码、脚本和测试。

Docker

docker build -t treasury-fiscaldata-mcp-server .
docker run --rm -e CANVAS_PROVIDER_TYPE=duckdb -p 3010:3010 treasury-fiscaldata-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/treasury-fiscaldata-mcp-server。原生构建主机依赖阶段会为目标架构交叉安装 DuckDB 绑定，同时保留版本发布期限和安全检查，并移除未使用的 musl 绑定。OpenTelemetry 对等依赖会按框架声明的版本范围安装；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config/	使用 Zod 解析并验证服务专属的环境变量。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）——5 个数据工具和 3 个 DataCanvas 工具，包括可选择启用的删除工具。
src/services/fiscal-data/	Treasury Fiscal Data API 客户端、内嵌端点目录和类型定义。
src/services/canvas-bridge/	框架 DataCanvas 的适配器：生成 df_<id>、设置每表 TTL、禁止访问系统目录的 SQL。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

请参阅 CLAUDE.md 和 AGENTS.md，了解开发指南和架构规则。简而言之：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 所有 Treasury API 值都是字符串——在下游 SQL 中验证并 CAST；不要伪造缺失字段
• 通过 src/index.ts 中的数组注册新工具

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。