exchange-rates-mcp-server

---

概要

Frankfurter v1 の日次為替レートに加え、現在の通貨情報を確認でき、1999-01-04 以降の履歴データを利用できます。金額の換算、特定時点または過去のレートの取得、期間全体の要約、ステージングされた時系列データに対する SQL の実行が可能です。過去データの対応状況には廃止済み通貨も含まれ、要求されたデータを基に確認されます。レスポンスには source: "Frankfurter v1" および rate_type: "Daily rate (Frankfurter v1)" が示されます。v1 のペイロードでは個別のプロバイダーは特定されません。API キーは不要です。

ツール

ツール	説明
fx_list_currencies	通貨コードを正式名称と最新の提供レート日付とともに確認します
fx_get_rates	基準通貨の全レートのスナップショットを、最新日または過去の日付で取得します
fx_get_rate	通貨ペアの為替レートを、最新日または過去の日付で取得します
fx_convert_currency	最新レートまたは過去のレートで、2つの通貨間の金額を換算します
fx_get_timeseries	指定した期間の通貨ペアの日次過去レートを取得します
fx_dataframe_describe	以前の fx_get_timeseries 呼び出しでステージングされた DataCanvas のテーブルと列を一覧表示します
fx_dataframe_query	ステージングされた DataCanvas テーブルに対して、読み取り専用の SQL SELECT を実行します
fx_dataframe_drop	ステージングされた DataCanvas のテーブルまたはビューを1つ削除します（オプトイン、破壊的操作）

DataCanvas（DuckDB）はデフォルトで有効です。無効にするには CANVAS_PROVIDER_TYPE=none を設定します。すると、3つの fx_dataframe_* ツールは tools/list から表示されなくなり、canvas_id を省略した場合、fx_get_timeseries は範囲データをインラインで返します。明示的なステージングは canvas_unavailable エラーになります。Claude Desktop バンドル（.mcpb）には DuckDB のネイティブバインディングが含まれていないため、DataCanvas を無効にして動作します。fx_dataframe_drop を使用するには、さらに FX_ENABLE_CANVAS_DROP=true が必要です。

レートおよび換算の4つのツールでは、base を base_currency の別名として使用できます。通貨ペアを扱うツールでは、quote も quote_currency の別名として使用できます。各フィールドにはどちらか一方の表記を指定し、両方を指定しないでください。公開されるスキーマでは正式な名前が使用されます。

通貨値は、symbols を含め、前後の空白が取り除かれ、大文字に変換されます。単一日の指定には YYYY-MM-DD またはリテラル値 latest（デフォルトも同じ）を使用できます。期間の指定には YYYY-MM-DD が必要です。公開される日付パターンにより、不正な形式、空欄、または暦上存在しない日付では、ハンドラー層の invalid_date_format エラーが保持されます。期間の終了日が未来の場合、エラーメッセージでは今日以前の end_date を指定するよう案内されます。end_date は引き続き必須です。

リソース

リソース	説明
fx://currencies	サポート対象のすべての通貨をまとめた、安定した参照ドキュメント
fx://rates/latest/{base}	基準通貨の最新レートのスナップショットを示す、安定した URI

すべてのリソースデータはツールからも取得できます。プログラムからアクセスするには、fx_list_currencies または fx_get_rates を使用してください。

ツール呼び出しまたはリソース読み取りをキャンセルすると、上流へのフェッチ、レスポンス本文の読み取り、再試行の待機が停止します。キャンセルされていないリクエストには、各試行につき10秒のタイムアウトと2回の再試行が適用されます。

機能リファレンス

fx_list_currencies _tool

• 入力パラメーターはありません
• currencies: [{ code, name }]、count、source、as_of（最新の提供日次レートの日付）を返します。コードのアルファベット順に並びます
• これは現在の通貨一覧を確認するためのツールです。過去の日付のリクエストは、フィルターされていない EUR スナップショットまたは提供された生データの範囲に基づいて検証されるため、廃止されたコードでも、観測値がある日付であれば使用できます。不明なコードの場合は、受け付け可能なコードと拒否されたコードをそれぞれソートして入力フィールドとともに示す unsupported_currency エラーになります。現在の通貨でも過去の観測値がない場合は、upstream_no_data エラーになります。

---

fx_get_rates _tool

• base_currency は必須です。date は省略可能です（デフォルトは最新日、履歴は1999-01-04以降、未来の日付は指定不可）。省略可能な symbols 配列でレスポンスを絞り込めますが、少なくとも1つのコードを指定する必要があります
• rates マップ（クオート通貨コード → レート）、実際の rate_date、および週末や祝日のリクエストが直前の営業日に調整された場合の date_snapped: true を返します
• 基準通貨を symbols に指定できます。この場合、上流には送信せず、レート1としてローカルで応答します
• 型付きエラー：invalid_date_format、unsupported_currency、date_out_of_range、upstream_no_data

---

fx_get_rate _ツール

• base_currency、quote_currency は必須です。date は任意です（デフォルトは最新日。履歴は 1999-01-04 から利用でき、未来の日付は指定できません）。
• rate、rate_date を返します。また、週末または祝日の指定日が直前の営業日に調整された場合は、date_snapped: true を返します。
• すべての通貨ペアは、フィルタリング前の単一の EUR スナップショットから、クォート通貨の EUR レッグ／ベース通貨の EUR レッグを、中間丸めなしで使用します。EUR のレッグは 1 です。同一通貨ペアが 1 を返すのは、実際の観測日のみです。
• 型付きエラー：invalid_date_format、unsupported_currency、date_out_of_range、upstream_no_data

---

fx_convert_currency _ツール

• base_currency、quote_currency、amount（0 より大きい値）は必須です。date は任意です（デフォルトは最新日。履歴は 1999-01-04 から利用でき、未来の日付は指定できません）。
• EUR↔任意の通貨、任意の通貨↔EUR、およびクロスレートの通貨ペア（例：USD→JPY）を、単一のアップストリーム呼び出しで処理します。
• quote_amount（小数点以下 6 桁に丸めた値）、rate、rate_date、date_snapped に加えて、レートの種類と出典を示す rate_type と source を返します。
• 型付きエラー：invalid_date_format、unsupported_currency、date_out_of_range、upstream_no_data

---

fx_get_timeseries _ツール

• base_currency、quote_currency、start_date、end_date は必須です（履歴は 1999-01-04 から利用でき、未来の日付は指定できません。start ≤ end）。既存のキャンバスに追加する場合は、任意の canvas_id を指定します。
• 500 公表営業日ごとにインライン結果をページ分割します。rate_count は常に範囲全体の件数です。ページを続けるには、truncated: true と next_start_date を使用します。
• FX_TIMESERIES_CANVAS_THRESHOLD_DAYS（デフォルトは 90 日）を超える範囲は、DataCanvas へのステージング対象になります。40,000 文字のプレビュー上限を超える系列では、spilled: true、canvas_id、table_name を返します。それより小さい系列と、CANVAS_PROVIDER_TYPE=none のデプロイ環境では、インラインでページ分割されます。
• 同一通貨ペアは、実際の観測日に 1 を返します。恒等ペア以外の各行には、同日の両方の EUR レッグが必要です。レッグが欠損していても、観測値を捏造することはありません。メンバーシップは、包括的な範囲指定による切り取り前の、提供されたすべての生の日付を使用するため、週末のみの空ウィンドウも維持されます。
• 空の範囲（週末または祝日のみ）の場合、エラーとは区別できるよう、説明用の notice とともに rate_count: 0 を返します。
• インラインプレビューに収まる長い範囲では、新たに取得したキャンバスを解放します。ステージングが失敗またはキャンセルされた場合も同様です。指定されたキャンバスは引き続き利用できます。
• 明示的に canvas_id を指定すると、短い範囲や空の範囲も含め、完全な結果を常に rate DOUBLE を使用してステージングします。テーブル名には毎回新しい識別子のサフィックスが付き、繰り返し呼び出しや同時呼び出しでも、以前のテーブルはすべて保持されます。不明な ID では canvas_not_found が発生し、DataCanvas が無効な場合は canvas_unavailable が発生します。プレビューにすべての観測値が含まれる場合、truncated は false です。
• 空でない結果には、summary: { mean, min: { rate, date }, max: { rate, date }, first: { rate, date }, last: { rate, date }, change_pct } が含まれます。ページ分割またはステージングの前に、要求された間隔内のすべての観測値を対象に計算されます。継続リクエストでは、より短い要求間隔を対象に集計されます。同値の極値では最も早い日付を選び、単一値および恒等ペアの変動は 0 です。系列が空の場合、summary は省略されます。平均は日次観測値の単純算術平均であり、税務当局や会計方針による推奨を示すものではありません。

---

fx_dataframe_describe _ツール

• canvas_id は必須です（以前の fx_get_timeseries 呼び出しで取得したもの）。
• 各ステージング済みテーブルの kind、row_count、列スキーマ（name、type、nullable）に加えて、expires_at を返します。
• fx_dataframe_query の前に必ず実行する必要があります。CANVAS_PROVIDER_TYPE=none の場合は登録されません。
• ID が存在しない、または有効期限切れの場合は canvas_not_found が発生します。

---

fx_dataframe_query _tool

• canvas_id と読み取り専用の SQL query が必須です。row_limit は正の整数で、デフォルトは 150 です。10,000 を超える値は 10,000 に制限され、要求値と適用値が通知されます。制限と切り詰めの通知は併記され、ページングの案内には適用後の上限値が使用されます。
• 複数の fx_get_timeseries 呼び出しで取得したテーブルをまたぐ集計、GROUP BY、ウィンドウ関数、JOIN に対応しています。
• 返される行数は最大 row_limit 行です。truncated: true と notice に、次ページ用の ORDER BY <column> LIMIT <n> OFFSET <m> の形式が示されます。安定したページングには ORDER BY が必須です。
• Markdown テーブルのセル内では、パイプ、山括弧、改行がセル内に収まるようエスケープされます。structuredContent には未加工の値が保持されます。
• CANVAS_PROVIDER_TYPE=none の場合は登録されません。型付きエラーは canvas_not_found、missing_table、invalid_query です。

---

fx_dataframe_drop _tool

• canvas_id と正確な table_name（fx_dataframe_describe から取得）が必須です。
• ステージング済みのテーブルまたはビューを 1 つ削除します。上流のレートデータには影響せず、fx_get_timeseries で再度ステージングできます。
• テーブルが存在したかどうかに応じて、dropped: true または false を返します。
• FX_ENABLE_CANVAS_DROP=true でない限り無効です。有効でない場合、tools/list には表示されず、有効化のヒントを含む名前は起動ログと HTTP ランディングページにのみ表示されます。また、CANVAS_PROVIDER_TYPE=none の場合も登録されません。

---

fx://currencies _resource

• パラメーターはありません。fx_list_currencies と同じペイロードを application/json として返し、現在の通貨情報として currencies、count、source、as_of を含みます。
• 単一の静的リソースとして一覧表示されます。

---

fx://rates/latest/{base} _resource

• base は URI 内の ISO 4217 通貨コードです。
• 提供される最新の日次スナップショットについて、base_currency、rate_date、rates マップ、rate_type、source を返します。
• 検出用のヒントとして、4 つのサンプル URI（EUR、USD、GBP、JPY）とともに一覧表示されます。

Features

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

レートデータ：

• Frankfurter v1 による、キー不要の日次データ
• スナップショットまたは期間ごとにフィルターなしの EUR データを 1 回リクエストし、ローカルでクロスレートを計算します。同じレスポンスから過去の通貨構成も取得します。
• 週末・祝日の日時の扱い：API が要求日とは異なる日付を返した場合、date_snapped で示します。
• 通貨の観測された公表日に基づき、同一通貨のレートはローカルで 1 として計算されます。
• インラインプレビューの予算を超える長期間の時系列は、全期間を対象とする SQL 集計のために DataCanvas にステージングされます（DuckDB、デフォルトで有効）。

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

• すべてのレスポンスにレートの出所情報（rate_type、source、rate_date、date_snapped）を含め、エージェントが信頼性と鮮度を判断できるようにします。
• 構造化されたエラーコントラクト：型付きの reason フィールド（unsupported_currency、date_out_of_range、invalid_query、…）により、呼び出し元は文字列を解析せず、失敗の種類に応じて処理を分岐できます。
• レスポンスの上限：インラインの時系列ページは next_start_date から続けられ、SQL の結果は row_limit で上限が設定されるため、無制限のペイロードを返す呼び出しはありません。
• 成功時の notice による補足：系列が空である理由、ページ分割された系列の続き、またはステージング済みのデータを読み取るツールを説明し、正当な 0 件の結果が失敗として受け取られないようにします。

---

はじめに

パブリックホストインスタンス

パブリックインスタンス（https://exchange-rates.caseyjhand.com/mcp）を利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "exchange-rates-mcp-server": {
      "type": "streamable-http",
      "url": "https://exchange-rates.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

API キーは不要です。Frankfurter はキーなしで利用できます。MCP クライアントの設定ファイルに以下を追加してください。

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

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

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

または、Docker を使用します。

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

長期間の時系列 SQL 分析用に、DataCanvas（DuckDB）はデフォルトで有効です。無効にするには、CANVAS_PROVIDER_TYPE=none を追加してください。データフレームツールは tools/list から表示されなくなり、canvas_id を省略した場合、fx_get_timeseries はインラインでページ分割します。明示的なステージングは canvas_unavailable で失敗します。

{
  "mcpServers": {
    "exchange-rates-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/exchange-rates-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "none"
      }
    }
  }
}

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します。

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

前提条件

• Bun v1.4.0 以上（または Node.js v24+）。
• API キーは不要です。Frankfurter は無料で、キーなしで利用できます。

インストール

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

git clone https://github.com/cyanheads/exchange-rates-mcp-server.git

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

cd exchange-rates-mcp-server

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

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env as needed (all vars are optional — no keys required)

---

設定

すべての設定は、起動時に Zod スキーマを使用して検証されます。環境変数：

変数	説明	デフォルト
FRANKFURTER_BASE_URL	Frankfurter API のベース URL です。ローカルテストまたはセルフホストインスタンス用に上書きできます。	https://api.frankfurter.dev/v1
FX_TIMESERIES_CANVAS_THRESHOLD_DAYS	fx_get_timeseries が自動的な DataCanvas ステージングを検討する日数のしきい値です。canvas_id がない場合、プレビューに収まる系列はインラインのままです。canvas_id を明示すると、常にステージングが要求されます。	90
FX_ENABLE_CANVAS_DROP	破壊的な fx_dataframe_drop ツールを有効にします。デフォルトでは無効です。このツールは登録されず、tools/list にも表示されません。	false
CANVAS_PROVIDER_TYPE	Canvas エンジンです。duckdb は fx_get_timeseries の長期間データのスピルオーバーに DataCanvas を有効にし、3 つの fx_dataframe_* ツールを登録します。none は無効にし、tools/list から除外します。空の値の場合はデフォルトが使用されます。.mcpb バンドルでは none が設定されています。	duckdb
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。auto、stateful、または stateless を指定します。サーバーはコード内で stateless を宣言しています。このサーバーのハンドラーは呼び出しの途中でクライアントに入力を求めないため、再開にセッションは必要ありません。この変数を設定すると、その宣言が上書きされます。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_REQUEST_STATE_KEY	オプトイン用のキー（32 バイト以上。すべてのインスタンスで同じ値）です。ハンドラーがラウンド間で返す requestState を保護します。このサーバーのツールは requestState を返しません。	—
MCP_LOG_LEVEL	ログレベルです（RFC 5424：debug、info、notice、warning、error）。クライアントに転送されるログの最低レベルにもなります。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します（キー名のみで機密情報を除去します）。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	LOG_TOOL_FAILURE_PAYLOADS のペイロードごとの上限です。UTF-8 のバイト数で指定します。	16384
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP のベース URL です。トレースは /v1/traces に、メトリクスは /v1/metrics に送信されます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトインで OTLP ログをエクスポートします（例：http://localhost:4318/v1/logs）。ベースエンドポイントを設定しても有効にはなりません。	—

ストレージ、セッション、テレメトリー関連の変数を含む、オプションの上書き設定の全一覧は .env.example を参照してください。

---

サーバーの実行

ローカル開発

• ビルドして実行します。

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

• チェックとテストを実行します。

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t exchange-rates-mcp-server .
docker run --rm -p 3010:3010 exchange-rates-mcp-server

Dockerfile のデフォルト設定は、HTTP トランスポート、ステートレスセッションモード、および /var/log/exchange-rates-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。DuckDB のネイティブバインディングを含む本番用依存関係は、独立した deps ステージでターゲットプラットフォーム向けにクロスインストールされるため、マルチアーキテクチャビルドで Bun がエミュレーション下で実行されることはなく、ランタイムイメージには node_modules と dist/ のみが含まれます。

---

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、キャンバスアクセサーを登録します。
src/config/	Zod による、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools/	ツール定義（*.tool.ts）です。fx_* ツールを定義します。
src/mcp-server/resources/	リソース定義です。fx://currencies と fx://rates/latest/{base} を定義します。
src/services/frankfurter/	Frankfurter HTTP クライアント、再試行ロジック、ドメイン型です。
src/services/canvas/	fx_get_timeseries のスピルオーバーに使用する、モジュールレベルの DataCanvas アクセサーです。
src/utils/	出力ヘルパーです。fx_dataframe_query 用の Markdown テーブルセルのエスケープを行います。
tests/	src/ の構成を反映した単体テストと統合テストです。
docs/	設計ドキュメントとアイデアのメモです。

---

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用してください。
• src/mcp-server/*/definitions/index.ts のバレル経由で、新しいツールとリソースを登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足フィールドを捏造しないでください。
• すべてのレスポンスで、来歴情報 rate_type: "Daily rate (Frankfurter v1)" と source: "Frankfurter v1" を保持してください。

---

コントリビューション

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

bun run devcheck
bun run test

---

ライセンス

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