NBG Rates (National Bank of Georgia)

nbg-rates-mcp

Claude やその他の MCP クライアントに、任意の日付のジョージア国立銀行（NBG）公式ラリ（GEL）レートを尋ねたり、そのレートで金額を換算したりできます。nbg-rates-mcp はお使いのマシン上、または claude.ai や ChatGPT に貼り付けて使えるホスト型コネクターとして動作します。アカウントもキーも不要です。また、単純な照会で間違えやすいルールも組み込まれています。通貨単位あたりの値、トビリシの暦日、独自のレートがない日を明示するフラグ、そして NBG がまだ公表していない日付には古いレートではなくエラーを返す仕組みです。

nbg-rates.env.ge：機能と追加方法について、英語とジョージア語で説明しています。

これは独立したオープンソースプロジェクトであり、ジョージア国立銀行とは提携していません。正確な情報は NBG のウェブサイト nbg.gov.ge をご確認ください。このサーバーが読み取る NBG のエンドポイントは文書化されておらず、変更される可能性があります。

尋ねられること

• 2026年9月30日の USD レートはいくらでしたか？
• 2026年9月27日の NBG レートで 1,500 USD を GEL に換算してください。
• 2026年9月の EUR レートを日ごとに表で示してください。
• 今日の NBG レートでは、1ユーロは何米ドルですか？

日付は月を単語で書いてください。「10 September 2026」のようにします。10/09/2026 では、2通りの日付として解釈されます。

2つ目の質問への回答は次のとおりです。2026年9月27日は日曜日なので、有効なレートは NBG が9月26日土曜日に設定した 1 USD あたり 2.6080 GEL で、日曜日も引き続き有効です。1,500 USD = 3,912.00 GEL であり、回答にはレートが26日から引き継がれていることが示されます。

Claude Desktop では、チャットの「+」メニューに、このサーバーからの既成の質問も4つ表示されます。今日のレート、指定した日付のレート、金額の換算、月間レート表です。

取得するレート

ジョージアの会計および税務報告では、取引日に有効な NBG の公式レートを使用します。このサーバーは、指定した日の nbg.gov.ge に表示されるレートをそのまま返します。

換算額は、NBG の公表値をもとに正確に計算され、帳簿への記帳と同じように小数第3位を四捨五入して小数第2位まで表示されます（resultRounded）。

NBG はトビリシ時間の17:00頃に営業日のレートを設定し、そのレートは翌暦日から有効になります。日曜日、月曜日、または祝日の翌日は独自のレートがなく、最後に設定されたレートが引き続き適用されます。回答にはその旨（carriedOver）と、レートの適用開始日が示されます。明日など、NBG がまだ公表していない日付については、トビリシ時間の17:00頃より前であっても、推測ではなく必ずエラーを返します。

インストール

claude.ai、Claude モバイル、ChatGPT（インストール不要）

この URL をカスタムコネクターとして貼り付けます。

https://nbg-rates.env.ge/mcp

claude.ai で「Customize」を開き、「Connectors」、「+ Add」、「Add custom connector」の順に選択し、URL を貼り付けて「Add」で完了します（Team または Enterprise プランの場合、オーナーが「Organization settings」の「Connectors」から追加します）。追加したコネクターは、同じアカウントの Claude モバイルアプリと Claude Desktop にも表示されます。ChatGPT では chatgpt.com/plugins を開き、プラスボタンを選択して「Add custom MCP server」を選び、「Connection」の下に URL を貼り付けます。認証はオフのまま「Create as a plugin」で完了します（ワークスペースでは、事前に管理者がカスタム MCP サーバーを許可する必要がある場合があります）。ランディングページの nbg-rates.env.ge に、各アプリの手順が順を追って記載されています。

このホスト型サービスは、このサーバーの最新リリースをメンテナーが AWS 上で実行しているものです。アカウントは不要で、問い合わせられた金額や通貨が記録されることはありません。過去の日付については、誰かが初めて問い合わせたときに NBG の表のコピーを保存しますが、そのコピーからは誰がいつ問い合わせたかは分かりません。30 日間、2 種類のログを保持します。どのクライアントからどのツールが呼び出されたか、および NBG が応答したかどうかのログと、ゲートウェイのアクセスログ（時刻、パス、ステータス、呼び出し元の IP アドレスとユーザーエージェント。claude.ai と ChatGPT の場合、呼び出し元は Anthropic または OpenAI のサーバーです）です。これらのログは、サービスの稼働維持、利用しているクライアントの確認、エラーや不正利用の調査にのみ使用します。販売、共有、広告には使用しません。ランディングページでは Cookie を設定せず、外部から何も読み込みません。

Claude Desktop（macOS、Windows）

nbg-rates-mcp-latest.mcpb をダウンロードして開きます。Claude Desktop が拡張機能をインストールし、独自の Node.js で実行するため、ほかに必要なものはありません。同じファイルが、バージョン番号付きで各リリースに添付されています。

Claude Desktop（Linux ベータ版）と手動設定

claude_desktop_config.json にサーバーを追加します。このファイルはまだ存在しない場合があります。その場合は、以下のスニペットを内容全体としてファイルを作成し、Claude Desktop を再起動してください。

プラットフォーム	claude_desktop_config.json の場所
macOS	~/Library/Application Support/Claude/
Windows	%APPDATA%\Claude\
Linux	~/.config/Claude/

{ "mcpServers": { "nbg-rates": { "command": "npx", "args": ["-y", "nbg-rates-mcp"] } } }

Node.js 22 以降が必要です。下記の Node.js を参照してください。

Claude Code

claude mcp add nbg-rates -- npx -y nbg-rates-mcp

すべてのプロジェクトでサーバーを使用できるようにするには、ユーザースコープで追加します。

claude mcp add --scope user nbg-rates -- npx -y nbg-rates-mcp

Cursor などのクライアント

同じ mcpServers エントリーを、クライアントの MCP 設定に追加します。Cursor の場合は、すべてのプロジェクトで使用するなら ~/.cursor/mcp.json に、1 つのプロジェクト内だけで使用するならそのプロジェクト内の .cursor/mcp.json に追加します。

Node.js

npx には Node.js 22 以降が必要です（Claude Desktop のバンドルには不要です）。node --version で確認し、必要であればインストールしてください。

• macOS（Homebrew）：

  brew install node
  

• Debian および Ubuntu（NodeSource、Node.js 24）：

  curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
  sudo -E bash nodesource_setup.sh
  sudo apt-get install -y nodejs
  

• その他の Linux ディストリビューション（nvm。1 行目の実行後、新しいターミナルを開いてください）：

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
  nvm install --lts
  

• Windows（PowerShell）：

  winget install OpenJS.NodeJS.LTS
  

• WSL：Debian および Ubuntu と同じコマンドを、WSL シェル内で実行します。

このドキュメントの以降の内容は、開発者と、モデル向けの手順を作成する方向けです。

セルフホスティング

同じサーバーは Streamable HTTP にも対応しています。nbg-rates-mcp --http --port 3000 を実行すると、http://127.0.0.1:3000/mcp でサービスが提供されます（すべてのインターフェースで待ち受けるには --host 0.0.0.0 を追加します）。AWS Lambda では、npm パッケージの本番用依存関係と一緒に ZIP 圧縮した dist/lambda.handler を、ペイロード形式 2.0 と $default ステージを使用する API Gateway HTTP API の背後に配置します（名前付きステージではすべてのパスの先頭にステージ名が付くため、各リクエストで 404 が返されます）。どちらの場合も、NBG_RATES_HTTP_HOSTS に公開ホスト名を設定すると、エンドポイントはそのホストに対してのみ応答します。任意で、NBG_RATES_MIRROR_TABLE に DynamoDB テーブル名を設定すると、同じ関数がスケジュールに従って NBG からデータを取得してテーブルに保存し、そのデータを使って応答します。設定しない場合、これまでどおり NBG に問い合わせます。

ツール

すべてのツールは読み取り専用です。日付はトビリシの暦日で、形式は YYYY-MM-DD です。各レートは通貨 1 単位あたりの GEL です。各ツールは結果を構造化コンテンツとして返し、同じ JSON をテキストブロックとしても返します。

nbg_get_rates

指定した暦日に有効な NBG 公式レートです。NBG が通貨によって 10、100、1000、または 10000 単位あたりでレートを公表する場合があります。レートは常に 1 単位あたりに換算され、元の組み合わせは nbgQuantity と nbgRate に保持されます。

入力：

名前	必須	説明
date	いいえ	暦日です。省略するとトビリシの今日の日付になります。翌日のレートは、トビリシ時間の約 17:00 以降に利用できます。
currencies	いいえ	返す ISO 4217 コードです。大文字・小文字は区別されず、重複は無視されます。例：["USD", "EUR"]。指定する場合、リストには 1 件以上含める必要があります。すべての通貨を対象にする場合は省略します。
language	いいえ	通貨名の言語です。en（デフォルト）または ka（ジョージア語）を指定します。コード、数値、日付はどちらも同じです。

出力：

• requestedDate：指定された日付。date が省略された場合はトビリシの今日の日付です。
• effectiveDate：返されたレートが適用された日付として、NBG が公表している日付です。
• carriedOver：requestedDate に有効なレートが、それより前の日に適用された場合は true です。これらは引き続き requestedDate の公式レートです。レートと併せて effectiveDate を示してください。
• rates：通貨ごとのエントリーです。code、name、rate（1 単位あたりの GEL）、diff（1 単位あたりの前回公表レートとの差）、nbgQuantity（NBG が元のレートを公表する単位数：1、10、100、1000、または 10000）、nbgRate（nbgQuantity 単位あたりの NBG 公表レート）が含まれます。0.000001 未満の値は、主に 1000 または 10000 単位あたりで公表される通貨の diff で、4e-7 のような指数表記の JSON 数値になります。
• unknownCodes：指定されたコードのうち、その日に NBG が公表していなかったものと、3 文字の通貨コードではない入力です。それ以外の指定コードには引き続き回答します。GEL もここに含まれます。すべてのレートは GEL 建てのため、表に GEL の行はありません。

使用例：2026-10-05（月曜日）に、ユーザーが 2026-10-04（日曜日）の AMD レートを問い合わせたとします。NBG は日曜日のレートを設定しないため、その日に有効なレートは 2026-10-03（土曜日）から有効なもので、NBG は 1000 ドラムあたり 7.1762 GEL として公表しています。次のリクエスト

{ "date": "2026-10-04", "currencies": ["AMD"] }

を送ると、次の結果が返されます。

{
  "requestedDate": "2026-10-04",
  "effectiveDate": "2026-10-03",
  "carriedOver": true,
  "rates": [
    {
      "code": "AMD",
      "name": "Armenian Dram",
      "rate": 0.0071762,
      "diff": 0.000012,
      "nbgQuantity": 1000,
      "nbgRate": 7.1762
    }
  ],
  "unknownCodes": []
}

同じリクエストを 2026-10-05（月曜日）に行った場合も、requestedDate が 2026-10-05 となり、同じレートが返されます。土曜日に適用されるレートとして金曜日に NBG が設定したレートは、月曜日も引き続き有効です。

nbg_convert

暦日付に適用されるNBG公式レートを使用して、2つの通貨間で金額を変換します。どちらか一方の通貨にはGELを指定できます。GELを含まない通貨ペアは、GELを介して変換されます。

入力：

名前	必須	説明
amount	はい	from通貨での金額です。有効な数値で、負の値も指定できます。
from	はい	ISO 4217コード、またはGELです。
to	はい	ISO 4217コード、またはGELです。
date	いいえ	適用する公式レートの暦日付です。デフォルトはトビリシの今日です。

出力：

• amount、from、to：大文字のコードを含むリクエストです。
• result：変換後の金額です。以降の計算に使えるよう、丸められていません。
• resultRounded：NBGの公開値から計算した正確な金額を四捨五入し、小数点以下2桁にしたものです。表示する金額です。JSONでは末尾のゼロが省略されるため、3.90は3.9として返されます。
• rate：fromの1単位をtoで表した値です。
• via：どちらか一方がGEL（または両方のコードが同じ）の場合はdirect、GELを含まない通貨ペアをGEL経由で変換する場合はGELです。
• requestedDate、effectiveDate、carriedOver：nbg_get_ratesと同じです。

GELからGELへの変換はそのままの値となり、NBGレートは必要ないため、有効な日付であればどの日付でも回答します。指定した日付にNBGがレートを公表していないコードはエラーになります。

nbg_convert_many

それぞれの金額を、各日付に適用されるNBG公式レートで変換します。請求書のリストを1回の呼び出しで処理できます。各項目は個別に処理されるため、無効な日付やコードがあっても、その項目だけが失敗します。サーバーは日付ごとに最大1回、NBGへ順番にリクエストします。NBGから応答がなくなると、まだ問い合わせていない日付はリクエストを送らず、同じエラーで失敗します。

入力：

名前	必須	説明
items	はい	{ amount, from, to, date? }形式の項目を1～100件指定します。各項目にはnbg_convertと同じルールが適用されます。

空のリスト、100件を超える項目、または{ amount, from, to, date? }の形式でない項目（amountがない、または数値でない、コードがない、テキストが64文字を超える項目）がある場合、入力スキーマで呼び出し全体が失敗します。それ以外の問題は該当する項目だけが失敗します。

出力：

• items：入力ごとに1つの項目を入力順で返します。変換に成功した項目は、resultRoundedを含むnbg_convertの出力です。失敗した項目は{ amount, from, to, date, error }です。入力された項目の内容が含まれ、dateが指定されていない場合はdateを含みません。errorには問題の内容を示すメッセージが入ります（Errorsを参照）。
• converted、skipped：変換された項目数と失敗した項目数です。
• total：{ to, resultRounded }です。1件以上の項目の変換に成功し、変換に成功したすべての項目の対象通貨が同じで、合計が有限の数値となる場合にのみ返されます。resultRoundedの値を正確に合計したもので、帳簿上の記帳済み明細の合計と同じ方法で計算されます。変換に成功した項目のみが対象となるため、skippedが0でない場合は一部の項目の合計です。

使用例：2026-10-10に10 USDと1.5 USDをGELに変換し、存在しない日付である2026-13-01に100 USDをGELに変換します。次のリクエスト

{
  "items": [
    { "amount": 10, "from": "USD", "to": "GEL", "date": "2026-10-10" },
    { "amount": 1.5, "from": "USD", "to": "GEL", "date": "2026-10-10" },
    { "amount": 100, "from": "USD", "to": "GEL", "date": "2026-13-01" }
  ]
}

を送信すると、次の結果が返されます。

{
  "items": [
    {
      "amount": 10,
      "from": "USD",
      "to": "GEL",
      "result": 26.005,
      "resultRounded": 26.01,
      "rate": 2.6005,
      "via": "direct",
      "requestedDate": "2026-10-10",
      "effectiveDate": "2026-10-10",
      "carriedOver": false
    },
    {
      "amount": 1.5,
      "from": "USD",
      "to": "GEL",
      "result": 3.9007499999999995,
      "resultRounded": 3.9,
      "rate": 2.6005,
      "via": "direct",
      "requestedDate": "2026-10-10",
      "effectiveDate": "2026-10-10",
      "carriedOver": false
    },
    {
      "amount": 100,
      "from": "USD",
      "to": "GEL",
      "date": "2026-13-01",
      "error": "2026-13-01 is not a valid calendar date (not a real calendar date); use YYYY-MM-DD."
    }
  ],
  "converted": 2,
  "skipped": 1,
  "total": { "to": "GEL", "resultRounded": 29.91 }
}

合計の26.01 + 3.9 = 29.91 GELは、変換に成功した2件の項目が対象です。skippedは1であるため、一部の項目の合計です。

nbg_list_currencies

NBGが今日のGELレートを公表しているすべての通貨を一覧表示します。NBGは過去にほかの通貨も公表していたため、ここにないコードでも過去のレートが存在する場合があります。

Inputs:

Name	Required	Description
language	no	通貨名の言語：en（デフォルト）または ka（ジョージア語）。

Output:

• effectiveDate：今日のレートが適用された日付です。
• currencies：通貨ごとの項目。code、name、nbgQuantity（NBGが元のレートを公表する際の単位数）が含まれます。

nbg_rate_history

指定した期間の各暦日に適用される、1通貨あたりのGELで表した公式レートです。1回の呼び出しでNBGに1回リクエストします。

Inputs:

Name	Required	Description
currency	yes	ISO 4217コード。例：USD。
from	yes	期間の初日（この日を含みます）。
to	yes	期間の最終日（この日を含みます）。fromを含めて最大366日です。

Output:

• currency、from、to：リクエスト内容です。コードは大文字に変換されます。
• days：暦日ごとの項目です。その日のレートが適用される場合は、rateを1単位あたりのGELレートとする { date, rate } になります。前日以前から引き継がれたレートの場合は、レートが適用された日付を示す effectiveDate と、carriedOver: true が追加されます。effectiveDateがない場合、レートはその日付自体に適用されたことを意味します。1年分でも約6,000トークンに収まります。
• summary：first、last、change（最終値から初期値を引いた値）、minとmax（それぞれ最初にその値になった日付を示すminDateとmaxDateを含みます）、および範囲内のすべての暦日について、レートが引き継がれた日も含めて算出した算術平均averageです。changeとaverageは、NBGの通貨単位数が示す小数桁数（4 + log10(nbgQuantity)、日ごとの最大値。USDでは4桁、AMDでは7桁）に、四捨五入（五捨六入）して正確に算出されます。

たとえば、金曜日の2026-10-02から火曜日の2026-10-06までのUSDの場合（土曜日には独自のレートがあり、日曜日と月曜日はそのレートが引き継がれます）：

{
  "currency": "USD",
  "from": "2026-10-02",
  "to": "2026-10-06",
  "days": [
    { "date": "2026-10-02", "rate": 2.6042 },
    { "date": "2026-10-03", "rate": 2.6039 },
    { "date": "2026-10-04", "rate": 2.6039, "effectiveDate": "2026-10-03", "carriedOver": true },
    { "date": "2026-10-05", "rate": 2.6039, "effectiveDate": "2026-10-03", "carriedOver": true },
    { "date": "2026-10-06", "rate": 2.6032 }
  ],
  "summary": {
    "first": 2.6042,
    "last": 2.6032,
    "change": -0.001,
    "min": 2.6032,
    "minDate": "2026-10-06",
    "max": 2.6042,
    "maxDate": "2026-10-02",
    "average": 2.6038
  }
}

NBGがまだ公表していない日付に及ぶ期間はエラーになります。また、NBGのエクスポートにその通貨のレートがない期間内の日（たとえばNBGが初めて公表する前、または公表を停止した後）もエラーになります。

リソース nbg://rates/{date}

暦日（YYYY-MM-DD）または today に適用される、NBGの公式レート表全体を、nbg_get_ratesの出力と同じフィールドを持つJSONとして返します。通貨名は英語です。nbg://rates/todayは、サーバーのリソース一覧に含まれています。

エラー

回答できないツールは、問題の内容と次に行うことを示すテキストを含むエラー結果を返します。

• 日付が YYYY-MM-DD 形式の実在する暦日ではない場合、または履歴の期間が開始日より前に終了している場合；
• 履歴の期間が366日を超える場合；
• 通貨が3文字のコードではない場合（メッセージには例としてUSD、EUR、GELが示されます）、またはNBGが要求された日付や期間にその通貨を公示していない場合（nbg_get_rates では、そのようなコードは代わりに unknownCodes に列挙されます）。NBGは長年の間に通貨を追加したり取り扱いを終了したりしているため、そのコードのレートが別の日付には存在する場合があります；
• 換算結果が大きすぎて数値として表現できない場合；
• NBGがその日に適用されるレートを保有していない場合（アーカイブは1995-10-14から始まり、NBGが初めて公示する前、NBGが公示を終了した後、またはNBGの記録に欠落がある期間には、通貨のレートがありません）；
• NBGがその日付のレートをまだ公表していない場合。メッセージにはトビリシの今日の日付が示され、レートが適用される可能性がある最も先の日付は明日であること、またNBGが公表した後に限られることが記されます。分かる場合は、最新の公表済みレートの適用開始日も示されます。この日付に達する履歴期間は全体が失敗します。終了日を今日までにしてください；
• NBGから使用可能な応答がなかった場合。リクエストは再試行できます；
• NBGの応答が想定した形式ではなかった場合。NBGのエンドポイントが変更された可能性があります。パッケージのバージョンを添えて、issueを作成してください。

リソースの読み取りでも、同じメッセージが表示されて失敗します。

日付のルール

• NBGはトビリシ時間の17:00頃に営業日のレートを設定します。このレートは翌暦日から次のレートが設定されるまで有効です。公表後は、日付を指定して翌日のレートをリクエストできます。
• 「今日」とは、クライアントの実行場所にかかわらず、トビリシの暦日を指します。
• 日曜日、月曜日、および祝日の翌日には独自のレートがありません。直前のレートが引き継がれ、carriedOver: trueとなり、effectiveDateにはそのレートの適用開始日が設定されます。2021年9月より前は、NBGが毎暦日のレートを保存していたため、それ以前の日曜日のレートは引き継ぎ扱いになりません。
• NBGがまだレートを公表していない日付（トビリシ時間の17:00頃より前の明日、またはそれ以降のすべての日付）では、推測ではなくエラーが返されます。
• NBGは、その日を過ぎてからその日のレート表を公表することがあります。2026-09-28（月）17:01に、NBGは2026-09-26（土）から適用されるレート表を公表し、2026-09-26から2026-09-28までの金曜日のレートを置き換えました。そのため、過去7日間の引き継ぎレートの回答は変わる可能性があります。サーバーはこの期間のレートを10分後に再度NBGに問い合わせ、それ以外の回答は12時間後に再度問い合わせます。
• アーカイブは1995-10-14のUSDから始まり、その他の通貨はそれより後に追加されています。

環境変数

変数	効果
NBG_RATES_BASE_URL	呼び出すNBGのホストです。デフォルトは https://nbg.gov.ge で、末尾のスラッシュは削除されます。テストに便利です。
NBG_RATES_DEBUG	1に設定すると、すべての上流リクエストを標準エラー出力に記録します。バグ報告にはこのログを含めてください。
NBG_RATES_HTTP_HOSTS	HTTPエンドポイント（--http、Lambda）が応答するホスト名を、カンマ区切りで指定します。未設定または空の場合、すべてのホストが対象です。
NBG_RATES_MIRROR_TABLE	ホスト型NBGミラーのDynamoDBテーブルです。Lambdaエントリのみが読み取ります。--httpとstdioでは無視されます。未設定または空の場合、ミラーはありません。
NBG_RATES_OPENAI_CHALLENGE	OpenAIのドメイン検証が /.well-known/openai-apps-challenge で要求するトークンです。プレーンテキストとして提供されます。未設定または空の場合、そのパスは404を返します。

クライアントの設定で、次のように設定します。

{
  "mcpServers": {
    "nbg-rates": { "command": "npx", "args": ["-y", "nbg-rates-mcp"], "env": { "NBG_RATES_DEBUG": "1" } }
  }
}

開発

npm install
npm test                 # unit tests
npm run test:e2e         # builds, then drives the server over stdio against recorded NBG responses
npm run test:contract    # live: checks the assumptions against nbg.gov.ge
npm run record-fixtures  # refreshes test/fixtures from nbg.gov.ge; review the diff before committing

プルリクエストを作成する前に、npm run format:check、npm run lint、npm run typecheck も実行してください。

コードは src/core と src/shell に分かれています。src/core には、I/O を伴わない純粋関数（日付ルール、解析、単位ごとの正規化、変換、履歴）が含まれています。src/shell には、副作用を伴う処理（NBG HTTP クライアント、キャッシュ、レートサービス、MCP サーバー）が含まれています。src/bin.ts は実行可能ファイルです。

リポジトリのルールセット（main の保護と、管理者のみが作成できるリリースタグ）は .github/rulesets/ で定義され、scripts/apply-rulesets.sh で適用されます。リポジトリの説明、ホームページ、トピックは .github/repository.json で定義され、scripts/apply-repo-settings.sh で適用されます。どちらも変更後にメンテナーが実行し、GitHub UI から編集することはありません。

ライセンス

MIT です。詳細は LICENSE をご覧ください。