treasury-fiscaldata-mcp-server

---

概要

米国財務省の財政データ：国債残高、金利、為替レート、その他の連邦財政データセットを扱います。主要な数値を 1 回の呼び出しで取得し、任意の Fiscal Data エンドポイントを照会して、大量に取得したデータに対して SQL を実行できます。

ツール

ツール	説明
treasury_list_datasets	厳選された 17 個の Treasury Fiscal Data エンドポイントのカタログを、フィールド名、説明、更新頻度とともに表示します
treasury_query_dataset	パス、フィールドリスト、フィルター、ソート、ページを指定して、任意の Treasury Fiscal Data エンドポイントを照会します（オプションで DataCanvas へのスピルに対応）
treasury_get_debt	国債残高（Debt to the Penny）を取得します。最新レコード、特定の日付、または期間別の系列を指定でき、オプションで DataCanvas へのスピルに対応します
treasury_get_interest_rates	種類別に、財務省が未償還証券に支払う平均金利を取得します。市場性証券、非市場性系列、総計が対象です
treasury_get_exchange_rates	約 165 か国を対象に、四半期ごとに公表される財務省の公式法定為替レートを取得します
treasury_dataframe_describe	treasury_* ツールによって実体化された DataCanvas データフレームを、スキーマ、行数、TTL とともに一覧表示します
treasury_dataframe_query	標準の DuckDB SQL を使用して、DataCanvas データフレームに対する単一ステートメントの SELECT を実行します
treasury_dataframe_drop	ステージング済みデータフレームとその出所情報を削除します（TREASURY_DATAFRAME_DROP_ENABLED=true の場合を除き無効）

機能リファレンス

treasury_list_datasets _tool

• カテゴリ（debt、interest_rates、exchange_rates、revenue_spending、savings_bonds、securities、other）またはキーワードで検索できます。
• ネットワーク呼び出しなしで、同梱カタログからエンドポイントパス、フィールド、型、更新頻度を返します。

---

treasury_query_dataset _tool

• { 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 です。
• SQL 分析用にページをステージングするには canvas_id を渡します。返される canvas_id は割り当てられたテーブル名です。

---

treasury_get_debt _tool

• 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 _tool

• mode=latest は最新月の金利を返し、必要に応じて security_type で絞り込めます。mode=series は日付範囲を受け付けます。
• 金利はパーセンテージで示されます。フィルターに一致するものがない場合は、利用可能な証券種別が表示されます。系列プレビューは最大 20 行です。
• 系列のステージングは 200 行を超える場合、または canvas_id によるリクエスト時に開始されます。

---

treasury_get_exchange_rates _tool

• 1 USD あたりの外貨単位で示す、四半期ごとの公式報告為替レートです。countries は完全一致する国名で絞り込みます。mode=latest は通貨ごとに現在の行を 1 件返し、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 _tool

• name を省略すると、テナントのアクティブなデータフレームが一覧表示されます。指定する場合は、テーブル名を完全一致で指定してください。
• データの出所、作成日時と有効期限、行数、列スキーマを返します。上限付きのソース取得については、truncated / max_rows で確認できます。
• テーブルの有効期限は、ステージングから 24h 後がデフォルトです。CANVAS_TTL_MS で設定できます。

---

treasury_dataframe_query _tool

• 読み取り専用の SELECT 文を 1 つ受け付けます。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 _tool

• 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 です。計算や日付比較を行う場合は、DECIMAL または DATE に CAST してください。DataCanvas には CANVAS_PROVIDER_TYPE=duckdb が必要です。設定済みのキャンバスツールは、それ以外の場合 canvas_unavailable を報告します。
• フィールドメタデータ付きの 17 エンドポイントの厳選カタログを備えているため、検出のためのラウンドトリップは不要です。カタログ外のデータセットには、任意のエンドポイントパスを treasury_query_dataset に直接渡してください。
• 最もよく検索される 3 つのデータセット（国債、金利、為替レート）向けの便利なツール
• DataCanvas 統合：大量取得データは df_<id> データフレームとして登録され、DuckDB SQL でクエリできます。ツールごとにステージングのしきい値が自動的に設定されます。
• API キーは不要です。US Treasury Fiscal Data API は無料で一般公開されています。

エージェントに適した出力：

• 出所情報：フィルター式のエコー（applied_filters）とフィールドラベルのマップ（field_labels）により、エージェントは送信内容を確認し、生のフィールド名を読み取れます。
• 補足通知：結果が空の場合の案内、国の一部不一致、キャンバスのステージング確認、系列の切り捨てに関する警告で、次に呼び出すツールを明示します。
• 適切な切り捨て：系列とクエリ結果には、行を黙って破棄する代わりに、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 ダウンロード版は、DataCanvas を無効にした状態で Treasury API クエリに対応します。このポータブルバンドルには、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 を使ってクエリします。 JOIN、集計、ウィンドウ関数、CTE に対応した標準的な DuckDB SELECT を使用します。計算を行う場合は、VARCHAR 列を DECIMAL または DATE に CAST してください。

-- 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 キーは不要です。US Treasury Fiscal Data API は無料で一般公開されています。
• DataCanvas SQL は、@duckdb/node-api とそのネイティブバインディングを含む npm および Docker のインストールでは、デフォルトで有効です。ポータブルなデスクトップ用 .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 は、データフレームの説明／クエリと、有効時の削除を支えます。none の場合、呼び出し可能なキャンバスツールは canvas_unavailable を返し、別途有効にしない限り削除ツールはツール一覧に表示されません。	duckdb（デスクトップバンドルでは none）
CANVAS_TTL_MS	DataCanvas データフレームごとの TTL（ミリ秒）です。	86400000（24時間）
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 の配列を通じて登録してください

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。