anirbanbasu-frankfurtermcp

Frankfurter MCP

Frankfurterは、欧州中央銀行などの情報源が公開する最新の為替レート、過去のデータ、時系列データを取得できる便利な API です。Model Context Protocol（MCP）を通じて公開される言語モデルエージェント向けのツールとして Frankfurter API にアクセスする必要がある場合は、Frankfurter MCP が役立ちます。

インストール

この MCP サーバーで利用できるツールを使う場合は、以下の「使用方法」>「クライアント」のサブセクションを参照してください。

このリポジトリをクローンするディレクトリを、以降では_作業ディレクトリ_または_WD_と呼びます。

プロジェクトのタスクを管理するには、justをインストールしてください。

uvをインストールしてください。仮想環境に最小限の依存関係でプロジェクトをインストールするには、_WD_でjust installを実行します。開発とテストに必要な、必須ではない依存関係もすべてインストールするには、代わりにjust install-allを実行します。

環境変数

以下は、アプリケーションの設定に使用できる環境変数の一覧です。環境変数のテンプレートは.env.templateファイルに用意されています。以下の表に記載されているデフォルト値は、.env.templateファイルの値と常に同じとは限らない点に注意してください。

次の環境変数には、FASTMCP_を接頭辞として付けて指定できます。HOST、PORT、DEBUG、LOG_LEVELです。

基盤となる HTTP クライアントは、HTTPX ライブラリに記載されている一部の環境変数も参照します。また、ホストされた API エンドポイントや中間 HTTP(S) プロキシサーバーで自己署名証明書を使用するために、SSL_CERT_FILEとSSL_CERT_DIRを設定できます。

Frankfurter MCP は、パフォーマンス向上のために Frankfurter API への呼び出しをキャッシュします。キャッシュには2種類の戦略があります。たとえば過去のレートの検索のように、特定のパラメーターに対するレスポンスが変化しない API 呼び出しには、最終使用時刻順（LRU）キャッシュを使用します。たとえば最新レートの検索のように、レスポンスが変化する API 呼び出しには、有効期限（TTL）キャッシュを使用し、デフォルトの有効期限は15分に設定されています。キャッシュのパラメーターは環境変数で調整できます。以下を参照してください。

変数	[デフォルト値] と説明
LOG_LEVEL	[INFO] ログのレベルです。このレベルを変更すると、同じ環境変数を使用する可能性がある他の依存ライブラリのログ出力にも影響します。有効な値については、Python logging documentationを参照してください。
HTTPX_TIMEOUT	[5.0] 内部の HTTP クライアントが Frankfurter API からの応答を待つ時間（秒）です。設定可能な値の範囲は 5.0～60.0 です。
HTTPX_VERIFY_SSL	[True] たとえば自己署名証明書を使用するプロキシサーバーを利用している場合、この変数を False に設定すると SSL 証明書の検証を無効にできます。ただし、False に設定することは_推奨されません_。代わりに、SSL_CERT_FILE と SSL_CERT_DIR の各変数を使用して、自己署名証明書を適切に設定してください。
FAST_MCP_HOST	[localhost] サーバーのトランスポート（以下を参照）が stdio に設定されていない場合に、MCP サーバーがバインドするホストを指定します。0.0.0.0 を指定してサーバーを任意の IP にバインドすると、セキュリティ上の脅威となることに注意してください。この設定はデモ環境でのみ使用してください。
FAST_MCP_PORT	[8000] サーバーのトランスポート（以下を参照）が stdio に設定されていない場合に、MCP サーバーがリッスンするポートを指定します。
CORS_MIDDLEWARE_ALLOW_ORIGINS	["localhost", "127.0.0.1"] サーバーのトランスポート（以下を参照）が stdio に設定されていない場合に、MCP サーバーで許可するクロスオリジンリソース共有（CORS）のオリジンを指定します。以下で説明する MCP インスペクターを使用して HTTP トランスポート経由でこのサーバーをテストする場合は、明示的に「*」を設定する必要があります（設定すると警告が表示されます）。
MCP_SERVER_TRANSPORT	[stdio] 設定できる値は stdio、sse、streamable-http です。ただし、.env.template ではデフォルト値が stdio に設定されています。
MCP_SERVER_INCLUDE_METADATA_IN_RESPONSE	[True] 各ツール呼び出しに対する MCP の応答に、追加のメタデータを含めるかどうかを指定します。たとえば、応答の取得に使用した Frankfurter サーバーの API URL などが追加のメタデータに含まれます。
FRANKFURTER_API_URL	[https://api.frankfurter.dev/v1] Frankfurter API をセルフホストする場合は、デプロイ先の API エンドポイントアドレスに変更してください。
LRU_CACHE_MAX_SIZE	[1024] API 呼び出し用の最長未使用時間（LRU）キャッシュの最大サイズです。設定可能な値の範囲は 128～65536 です。
TTL_CACHE_MAX_SIZE	[256] API 呼び出し用の有効期限（TTL）キャッシュの最大サイズです。設定可能な値の範囲は 64～16384 です。
TTL_CACHE_TTL_SECONDS	[900] API 呼び出し用の有効期限（TTL）キャッシュの有効期間（秒）です。設定可能な値の範囲は 60～3600 です。
UVICORN_LIMIT_CONCURRENCY	[100] サーバーが受け入れる同時接続の最大数です。これにより、同時接続が多すぎることによるリソース枯渇を防げます。HTTP トランスポート（sse または streamable-http）を使用する場合にのみ適用されます。設定可能な値の範囲は 10～10000 です。
UVICORN_TIMEOUT_KEEP_ALIVE	[60] アイドル状態の接続を維持するタイムアウト（秒）です。リソースを解放するため、この時間が経過するとアイドル状態の接続は閉じられます。HTTP トランスポート（sse または streamable-http）を使用する場合にのみ適用されます。設定可能な値の範囲は 60～300 です。
UVICORN_TIMEOUT_GRACEFUL_SHUTDOWN	[5] グレースフルシャットダウンのタイムアウト（秒）です。サーバーは、強制終了する前に、アクティブな接続が完了するまでこの時間だけ待機します。HTTP トランスポート（sse または streamable-http）を使用する場合にのみ適用されます。設定可能な値の範囲は 5～60 です。
RATE_LIMIT_MAX_REQUESTS_PER_SECOND	[10.0] トークンバケットアルゴリズムを使用して許可される、1 秒あたりのリクエスト最大数です。API の不正利用を防ぎ、リソースを公平に割り当てるためのレート制限を実装します。設定可能な値の範囲は 1.0～10000.0 です。
RATE_LIMIT_BURST_CAPACITY	[20] レートリミッターのバースト容量です。1 秒あたりの制限を超えるリクエストを短時間にまとめて許可できます。持続的に高いリクエストレートから保護しつつ、正当な使用パターンに柔軟に対応できます。設定可能な値の範囲は RATE_LIMIT_MAX_REQUESTS_PER_SECOND の値の 2～5 倍です。
REQUEST_SIZE_LIMIT_BYTES	[102400] HTTP リクエストボディの最大サイズ（バイト単位、デフォルトは 100KB）です。この上限を超えるリクエストは、413 ステータスコードで拒否されます。これにより、大きなペイロードによるメモリ枯渇攻撃を防ぎます。HTTP トランスポート（sse または streamable-http）を使用する場合にのみ適用されます。設定可能な値の範囲は 10240（10KB）～524288（512KB）です。
DOCKER_TMPFS_SIZE_MB	[100] ルートファイルシステムを読み取り専用にして Docker で実行する場合の、一時ファイルシステム（/tmp）のサイズ（メガバイト単位）です。この一時ストレージは、実行時のファイル操作に使用されます。アプリケーションでキャッシュや大規模なデータセットの処理により多くの一時ストレージが必要な場合は、この値を増やしてください。Docker Compose でデプロイする場合にのみ関係します。

使用方法

以下の各節では、Frankfurter MCP をサーバーとして実行する方法と、MCP クライアントからアクセスする方法を説明します。

サーバー

サーバーの実行時には、stdio トランスポートまたは HTTP オプション（sse または新しい streamable-http）を選択できます。

デフォルト設定を使用し、MCP_SERVER_TRANSPORT を sse または streamable-http に設定すると、MCP エンドポイントは HTTP 経由で利用できるようになります。Server Sent Events（SSE）トランスポートの場合は http://localhost:8000/sse、ストリーミング可能な HTTP トランスポートの場合は http://localhost:8000/mcp です。

stdio トランスポートとデフォルトのパラメーターを使用して Frankfurter MCP を実行する場合は、.env.template ファイルを使用せずに、以下のコマンドを実行してください。

uv を使用したサーバー

任意: 前述の環境変数を変更する場合は、.env.template ファイルを WD に .env ファイルとしてコピーしてください。あるいは、シェルで変更したい環境変数をエクスポートできます。

MCP サーバーを起動するには、WD で以下を実行します。

uv run frankfurtermcp

PyPI パッケージから pip を使用したサーバー

仮想環境（uv、pyenv、conda で管理してもかまいません）で pip を使用して PyPI からこのパッケージを追加し、以下を実行してサーバーを起動します。

任意: 前述の環境変数のデフォルト値を変更する場合は、.env.template ファイルの内容を記載した .env ファイルを追加してください。あるいは、シェルで変更したい環境変数をエクスポートできます。

pip install frankfurtermcp
python -m frankfurtermcp.server

Docker を使用したサーバー

このリポジトリには、Frankfurter MCP サーバーをコンテナ化するための Dockerfile local.dockerfile が用意されています。まず、.env.template を .env ファイルにコピーします。次に、必要に応じて .env ファイル内の次の変数を変更します。

• FASTMCP_HOST：コンテナへの外部アクセスを許可するには、0.0.0.0 に設定します。これはローカルでのテスト専用であり、本番環境へのデプロイには推奨されません。
• CORS_MIDDLEWARE_ALLOW_ORIGINS：任意のオリジンから MCP サーバーへの外部アクセスを許可するには、* に設定します。HTTP トランスポートで MCP Inspector を使用してサーバーをテストする場合に必要ですが、本番環境へのデプロイには推奨されません。

イメージをビルドし、Docker Compose を使用してコンテナを作成して起動するには、WD で次を実行します。

.env でポートを 8000 以外に変更した場合は、docker-compose.yml のポート番号も忘れずに変更してください。

注：必要な Docker Compose の最小バージョンは 2.24.0 です。docker compose version を実行するとバージョンを確認できます。古いバージョンを使用している場合は、Docker Compose を最新の状態にするために Docker Desktop を更新してください。また、バックエンドは BuildKit に対応している必要があります。

docker compose up --build

デタッチモード（バックグラウンド）で実行するには、-d フラグを追加します。

docker compose up -d --build

コンテナを停止するには、次を実行します。

docker compose down

コンテナを実行してローカルの Frankfurter API サーバーを使用するには、次のコマンドを実行します。デタッチモードで実行するには、-d フラグを付けます。ローカル API サーバーで使用するオプションの環境変数を指定するには、local_api.env.template ファイルを確認してください。

注：初回起動時、ローカルの Frankfurter API が最新の為替レートを取得するまでに時間がかかる場合があります。2 回目以降の実行では、ローカルの Frankfurter API はキャッシュされたデータを使用するため、起動は速くなるはずですが、引き続き最新のレートを取得します。

FRANKFURTER_API_URL=http://frankfurter_api:8080/v1 docker compose --profile local_api up --build frankfurtermcp frankfurter_api

local_api プロファイルで作成したコンテナグループを停止するには、次のコマンドを実行します。

docker compose --profile local_api down

docker-compose.yml ファイルには、読み取り専用ファイルシステム（該当する場合）、ケイパビリティの削除、リソース制限によるセキュリティ強化が含まれています。

注：ローカル API サーバーは Frankfurter GitHub リポジトリ の最新コードを使用してビルドされるため、不安定な場合があります。特定のコミットを使用する場合は、docker-compose.yml ファイル内の frankfurter_api_base の build にある context フィールドを、特定のコミットハッシュを指すように変更してください。たとえば、コミット 0b6dbd80716f5abe27e8759fc548b74d35fa82b9 を使用するには、https://github.com/lineofflight/frankfurter.git#0b6dbd80716f5abe27e8759fc548b74d35fa82b9 を指定します。

ビルドとコンテナの起動が正常に完了すると、MCP サーバーは Server Sent Events（SSE）トランスポート用の http://localhost:8000/sse、またはストリーム可能な HTTP トランスポート用の http://localhost:8000/mcp で HTTP 経由で利用できます。ローカルの Frankfurter API サーバーも起動している場合、API エンドポイントは http://localhost:8080/v1 で利用できます。

クラウドホスト型サーバー

現在利用可能なクラウドホスト型の選択肢は次のとおりです。

• FastMCP Cloud: https://frankfurtermcp.fastmcp.app/mcp
• Glama.AI: https://glama.ai/mcp/servers/@anirbanbasu/frankfurtermcp

クライアントアクセス

このサブセクションでは、クライアントが FrankfurterMCP サーバーに接続してテストする方法を説明します。

公式 MCP ビジュアルインスペクター

MCP Inspector は、開発者が MCP サーバーをテストおよびデバッグするために使用できる、公式の Model Context Protocol ツールです。MCP サーバーを探索する最も包括的な方法です。

使用するには、Node.js がインストールされている必要があります。MCP Inspector などのパッケージと同様に、node をインストールして管理する最適な方法は、Node Version Manager（nvm）を使用することです。nvm をインストールしたら、以下を実行して node の最新の長期サポート版をインストールし、使用できます。

nvm install --lts
nvm use --lts

続いて、WD で以下を実行して MCP Inspector を（インストールし、）起動します。

npx @modelcontextprotocol/inspector uv run frankfurtermcp

これにより、認証トークン付きのローカル URL がポート 6274 に作成されます。この URL をコピーして、ブラウザーで開いてください。MCP Inspector の UI が表示されたら、Connect を押して MCP サーバーに接続します。その後、サーバーで利用できるツールを確認できます。

Claude Desktop、Visual Studio など

Claude Desktop、Visual Studio Code などのシステムで使用できる、stdio トランスポートで実行するサーバーエントリーは次のとおりです。

{
    "command": "uv",
    "args": [
        "run",
        "frankfurtermcp"
    ]
}

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

{
    "command": "uvx",
    "args": [
        "frankfurtermcp"
    ]
}

args のリストの最後の項目として frankfurtermcp を指定する代わりに、たとえば WD/.venv/bin/frankfurtermcp のように、スクリプトへのフルパスを指定する必要がある場合があります。同様に、uv を使用する代わりに、たとえば python3.12 のパスを適切に置き換えた、次の JSON 設定を使用することもできます。WD/.venv/bin/python3.12 のように指定します。

{
    "command": "python3.12",
    "args": [
        "-m",
        "frankfurtermcp.server"
    ]
}

利用可能な MCP 機能の一覧

FrankfurterMCP には、次の MCP 機能があります。

ツール

次の表は、FrankfurterMCP サーバーが公開するツール名の一覧です。ここに示す説明はドキュメント用であり、Model Context Protocol を介して公開される実際の説明とは異なる場合があります。

名前	説明
get_supported_currencies	Frankfurter API がサポートする通貨の一覧を取得します。
get_latest_exchange_rates	指定した基準通貨について、特定の通貨の最新為替レートを取得します。
convert_currency_latest	最新の為替レートを使用して、ある通貨から別の通貨に金額を換算します。
get_historical_exchange_rates	指定した基準通貨について、特定の日付または日付範囲の特定の通貨の過去の為替レートを取得します。
convert_currency_specific_date	特定の日付の為替レートを使用して、ある通貨から別の通貨に金額を換算します。
greet	FrankfurterMCP サーバーからあいさつを取得します。主に内部テストで使用します。

簡潔さを保つため、各ツールの必須引数と任意引数は次の表に記載していませんが、プロトコルを介して MCP クライアントから利用できます。

コントリビューション

prek をインストールします。その後、WD で次のコマンドを実行して prek を有効にします。

prek install

プルリクエストを歓迎します。大きな変更を行う場合は、まず issue を作成し、変更したい内容について話し合ってください。

テストとカバレッジ

提供されているテストケースを実行するには、次のコマンドを実行します。コンソールにさらに出力を表示するには、コマンドにフラグ --capture=tee-sys を追加してください。

uv run --group test pytest tests/

just test-coverage を実行すると、すべてのテストが実行され、次のようにカバレッジレポートが生成されます。すべてのテストを実行した場合、生成されるカバレッジレポートは以下のようになります。

---------------------------------------------------------------------------------------- benchmark: 2 tests ---------------------------------------------------------------------------------------
Name (time in ms)                         Min               Max              Mean            StdDev            Median               IQR            Outliers       OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_get_historical_exchange_rates     4.4944 (1.0)      5.1512 (1.0)      4.7919 (1.0)      0.2460 (1.0)      4.7819 (1.0)      0.3249 (1.0)           2;0  208.6840 (1.0)           5           1
test_get_latest_exchange_rates         4.7937 (1.07)     5.6976 (1.11)     5.3257 (1.11)     0.3345 (1.36)     5.4182 (1.13)     0.3575 (1.10)          2;0  187.7702 (0.90)          5           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
=============================================================== 15 passed in 4.09s ===============================================================
Name    Stmts   Miss    Cover   Missing
---------------------------------------
TOTAL     265      0  100.00%

6 files skipped due to complete coverage.
Test coverage complete.

ライセンス

MIT。

セキュリティに関する考慮事項

このセクションでは、脆弱性スキャンで見つかったセキュリティ関連の調査結果を記録し、デプロイに関する判断の背景を説明します。

Airtable の脆弱性スキャンの検出結果と根拠

the Airtable vulnerability scan（frankfurtermcp を検索）で検出されたセキュリティ関連の指摘と、その根拠および反論を以下に示します。

ルール ID	問題と反論
MCP-R001	問題：ツールはサーバーの起動時に動的に登録されますが、暗号署名、不変のバージョン管理、整合性チェックがありません。アーキテクチャでは（register_features パターンを介した）ホットリロードが可能ですが、署名の検証や承認フローはありません。 反論：ツールは外部ソースやプラグインから読み込まれるのではなく、アプリケーションのソースコードに直接定義されています。整合性は、バージョン管理とコードレビューのプロセスによって確保されています。ツールは（動的に読み込まれるプラグインではなく）アプリケーションバイナリの一部であるため、暗号署名を導入しても、複雑さが増すだけで有意なセキュリティ上の利点はありません。
MCP-R004	問題：サーバーは警告を出しますが、CORS のオリジンにワイルドカードを指定しても受け入れます。 反論：このサーバーは、HTTP トランスポートを使用する場合、本番環境で直接実行することを想定していません。より厳格な CORS オリジン制御が必要な環境にデプロイする場合は、.env.template の既定値（127.0.0.1）を使用し、適切な CORS オリジン制御をリバースプロキシ側に設定したうえで、サーバーを独自のリバースプロキシの背後にデプロイしてください。
MCP-R013	問題：サーバーが 127.0.0.1 以外の IP にバインドされている場合、HTTPS に対応していません。 反論：このサーバーは、HTTP トランスポートを使用する場合、HTTPS 対応の本番環境で直接実行することを想定していません。HTTPS 対応が必要な環境にデプロイする場合は、.env.template の既定値（127.0.0.1）を使用し、適切な HTTPS 設定を行ったうえで、サーバーを独自のリバースプロキシの背後にデプロイしてください。
MCP-R018	問題：認証や認可のチェックがありません。 反論：このサーバーは、HTTP トランスポートを使用する場合、複数のユーザーが利用するモードで直接実行することを想定していません。アクセス制御が必要な環境にデプロイする場合は、.env.template の既定値（127.0.0.1）を使用し、適切なセキュリティ制御を設定したうえで、サーバーを独自のリバースプロキシの背後にデプロイしてください。

プロジェクトのステータス

この README の最終更新時点で、プロジェクトの現在のステータスはアクティブです。変更の詳細な一覧については、CHANGELOG をご覧ください。