fred-mcp-server

---

概要

FRED は、セントルイス連邦準備銀行が運営するデータベースで、産出、物価、雇用、通貨、金利、住宅、貿易に関する約 80 万件の時系列データを収録しています。系列を検索して観測値を取得し、カテゴリやリリースを参照するほか、大量の結果に対して SQL を実行できます。

ツール

ツール	説明
fedreserve_search_series	FRED の系列のタイトル、タグ、注記を全文検索します
fedreserve_get_series	1 つ以上の系列のメタデータ（タイトル、単位、頻度、観測期間）を取得します
fedreserve_get_observations	1 つ以上の系列の日時と値の観測データを取得します。期間と単位変換による絞り込みに対応しています
fedreserve_browse_categories	FRED のカテゴリツリーを参照します
fedreserve_get_release	ID または名前で FRED のリリースを検索し、関連する系列を取得します
fedreserve_dataframe_describe	データの出所、スキーマ、行数とともに、アクティブな DataCanvas データフレームを一覧表示します
fedreserve_dataframe_query	DuckDB SQL を使用して、登録済みの DataCanvas データフレームに対して SELECT を実行します
fedreserve_dataframe_drop	名前を指定して DataCanvas データフレームを削除します（オプトイン）

機能リファレンス

fedreserve_search_series _tool

• 全文検索または系列 ID 検索に対応し、frequency、units、seasonal_adjustment、tag_names で絞り込めます。filter_variable と filter_value は必ずセットで指定してください。そうでない場合、呼び出しは invalid_filter を返します
• limit（デフォルトおよび最大値は 1000）と offset（最大値は 4999。FRED が検索可能な結果を 5000 件に制限しています）によるページネーション
• 出力には、利用可能な場合、active_filters と popularity（0～100）が含まれます。結果が空の場合は、検索語を広げるかカテゴリを参照してください

---

fedreserve_get_series _ツール

• 1つの系列 ID、または1回の呼び出しで最大50件を受け付けます
• 系列ごとにタイトル、単位、頻度、季節調整、観測期間、人気度、注記を返します
• 一括処理で失敗した ID は、エラーメッセージとともに failed 配列に格納されます。解決できない ID が1つだけの場合は series_not_found がスローされます

---

fedreserve_get_observations _ツール

• 1つの系列 ID、または最大10件を受け付けます。observation_start / observation_end（YYYY-MM-DD）、ネイティブ単位の変換、aggregation_method（avg、sum、eop）による頻度のダウンサンプリングを指定できます
• 日付と値の観測データを返します（値は末尾のゼロを保持する文字列です）。系列ごとのエラーも返します
• 複数系列の結果、または500行を超える結果は、20行のプレビュー付きで DataCanvas テーブルに格納されます。notice には dataset.name と、次に実行する fedreserve_dataframe_describe および fedreserve_dataframe_query の呼び出しが示されます。Canvas がない場合は、切り詰められたインラインプレビューが返されます

---

fedreserve_browse_categories _ツール

• category_id を省略するとルート（ID 0）から開始します。カテゴリとその子カテゴリ、または末端カテゴリの場合は最大10件のサンプル系列を返します
• 不明な category_id を指定すると category_not_found がスローされます

---

fedreserve_get_release _ツール

• release_id または release_search（大文字と小文字を区別しない名前の部分一致）のいずれか1つを指定します
• リリース名、リンク、注記、次回以降の予定日5件、ページ分割された系列一覧（series_limit は最大1000、series_offset）を返します
• 名前が曖昧な場合は最大10件の search_alternatives を返します。正確な release_id で再試行してください

---

fedreserve_dataframe_describe _ツール

• アクティブな DataCanvas データフレームを新しい順に一覧表示するか、name で1つを指定します
• 各エントリには source_tool、query_params、created_at、expires_at、row_count、truncated / max_rows、column_schema が含まれます

---

fedreserve_dataframe_query _ツール

• df_<id> テーブルに対して読み取り専用の DuckDB SELECT を1つ実行します（結合、集計、ウィンドウ関数、CTE に対応）。外部ファイル、システムカタログ、エンジン設定関数はブロックされます
• row_limit は返される行数の上限を設定します（デフォルトは1000、最大10000）。preview はインラインのサンプルを設定します。BIGINT の結果は文字列としてシリアライズされます
• register_as は、独自の TTL を持つ新しいデータフレームとして結果を保存します

---

fedreserve_dataframe_drop _ツール

• オプトイン機能です。FRED_DATAFRAME_DROP_ENABLED=true で有効になり、それ以外の場合は無効として登録されます
• 指定したデータフレームを早期に削除します。存在しない場合は dropped: false を返します

特長

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

FRED 固有の機能：

• FRED API を利用するには FRED_API_KEY が必要です（最大120リクエスト/分）
• 単位変換と頻度のダウンサンプリングは、系列の全履歴を対象に FRED 側で実行されます
• 大量の観測結果は、SQL でクエリできる DataCanvas テーブルに格納されます
• データフレームツールには CANVAS_PROVIDER_TYPE=duckdb が必要です。未設定の場合は canvas_unavailable が返されます

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

• 部分的な失敗：fedreserve_get_series と fedreserve_get_observations はリクエスト全体を失敗させず、ID ごとの failed 行を返します
• 曖昧なリリース名には推測で応答せず、search_alternatives を返します
• すべてのデータフレームには source_tool、query_params、TTL フィールドが含まれます
• DataCanvas がない場合、fedreserve_get_observations は説明用の message を添えて、切り詰められたインラインプレビューを返します

はじめに

以下を MCP クライアントの設定ファイルに追加してください。research.stlouisfed.org/docs/api/api_key.html で無料の FRED API キーを取得してください。

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用します（Bun は不要です）：

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

または Docker を使用します：

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FRED_API_KEY=your-api-key",
        "ghcr.io/cyanheads/federal-reserve-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください：

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

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• stlouisfed.org から取得できる無料の FRED API キー。キーにより、1 分あたり 120 件のリクエストが許可されます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/federal-reserve-mcp-server.git

2. ディレクトリに移動します：

cd federal-reserve-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set FRED_API_KEY

設定

起動時に、src/config/server-config.ts の Zod スキーマを使ってすべての設定が検証されます。

変数	説明	デフォルト
FRED_API_KEY	必須。 stlouisfed.org から取得した API キーです。	—
FRED_BASE_URL	FRED API のベース URL を上書きします。	https://api.stlouisfed.org/fred
FRED_DATASET_TTL_SECONDS	DataCanvas の観測テーブルの TTL（秒単位）です。	86400
FRED_DATAFRAME_DROP_ENABLED	true に設定すると fedreserve_dataframe_drop が有効になります。それ以外の場合は無効として登録されます。	false
CANVAS_PROVIDER_TYPE	duckdb に設定すると、観測結果に対する DataCanvas の SQL クエリが有効になります。	—
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレース（/v1/traces）とメトリクス（/v1/metrics）のベース OTLP URL です。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログエンドポイントです（設定されていない場合、ログは無効です）。	—
LOG_TOOL_FAILURE_PAYLOADS	キー名をマスキングして、失敗したツールの引数と結果を記録します。自由形式の値に含まれるシークレットはマスキングされません。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	記録するペイロードごとの最大バイト数です。	16384

オプションで上書きできる設定の一覧は .env.example を参照してください。

観測テーブルに対する SQL を有効にするには、CANVAS_PROVIDER_TYPE=duckdb に設定します。npm インストールと Docker イメージには DuckDB ランタイムが含まれます。ポータブル版の Claude Desktop バンドルにはネイティブバインディングが含まれません。キャンバスモードを使うには、npm または Docker でインストールしてください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  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
  

Docker

docker build -t federal-reserve-mcp-server .
docker run --rm -e FRED_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 federal-reserve-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/federal-reserve-mcp-server に記録されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント。ツールを登録し、サービスを初期化します。
src/config	Zod による、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。FRED ドメインと DataCanvas にまたがる 8 つのツールがあります。
src/services/fred	FRED API サービスです。HTTP クライアント、リトライ、429 の処理、キーの挿入を行います。
src/services/canvas-bridge	DataCanvas アダプターです。テーブル命名、TTL／来歴の追跡、SQL ゲートの追加機能を提供します。
tests/	src/ と対応する単体テストおよび統合テストです。
docs/	設計および計画に関するドキュメントです。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使用しないでください
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用してください
• 新しいツールは src/mcp-server/tools/definitions/index.ts に登録してください
• FRED API 呼び出しをラップします。生のレスポンスを検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足しているフィールドを捏造してはいけません

貢献

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。