Nbg Rates MCP Server

nbg-rates-mcp

Ask Claude, or any other MCP client, for the official National Bank of Georgia (NBG) rate of the lari (GEL) on any date, or to convert an amount at that rate. nbg-rates-mcp runs on your machine or as a hosted connector you paste into claude.ai or ChatGPT, needs no account and no key, and encodes the rules a raw lookup gets wrong: per-unit values, Tbilisi calendar days, an explicit flag when a day has no rate of its own, and an error, never a stale rate, for a date NBG has not published yet.

This is an independent open-source project, not affiliated with the National Bank of Georgia. NBG's website, nbg.gov.ge, is the source of truth. The NBG endpoints this server reads are undocumented and may change.

What you can ask

• What was the USD rate on 30 September 2026?
• Convert 1,500 USD to GEL at the NBG rate of 27 September 2026.
• Give me the EUR rate for every day of September 2026 as a table.
• How many US dollars is 1 euro today, at NBG rates?

Write the date with the month as a word, "10 September 2026": 10/09/2026 reads as two different dates.

For the second question the answer is: 27 September 2026 is a Sunday, so the rate in force is the one NBG set for Saturday 26 September, 2.6080 GEL per USD, still valid on Sunday; 1,500 USD = 3,912.00 GEL, and the answer says the rate is carried over from the 26th.

In Claude Desktop the "+" menu of a chat also lists four ready-made questions from this server: today's rates, the rate on a date, converting an amount, and a rates table for a month.

Which rate you get

Georgian accounting and tax reporting use the official NBG rate in force on the date of the transaction. This server returns exactly that rate, the one shown on nbg.gov.ge for the day you name.

Converted amounts come rounded half up to two decimals (resultRounded), the way a ledger posts them, computed exactly from NBG's published figures.

NBG sets rates on business days around 17:00 Tbilisi time, valid from the next calendar day. A Sunday, a Monday or the day after a public holiday has no rate of its own and keeps the last one set; the answer says so (carriedOver) and names the day that rate took effect. A date NBG has not published yet, including tomorrow before about 17:00 Tbilisi time, is answered with an error, never a guess.

Install

claude.ai, Claude mobile and ChatGPT (nothing to install)

Paste this URL as a custom connector:

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

On claude.ai open Customize, then Connectors, then "+ Add" and "Add custom connector", paste the URL and finish with "Add" (on a Team or Enterprise plan an owner adds it under Organization settings, then Connectors); the connector then also appears in the Claude mobile apps and in Claude Desktop under the same account. In ChatGPT, custom connectors need developer mode and may require a paid plan.

This hosted copy is the latest release of this server, run by the maintainer on AWS. It needs no account and never records the amounts, dates or currencies asked. It keeps two logs for 30 days: which tool was called from which client, and the gateway's access log (time, path, status, and the caller's IP address and user agent; for claude.ai and ChatGPT the caller is Anthropic's or OpenAI's server).

Claude Desktop (macOS, Windows)

Download nbg-rates-mcp-latest.mcpb and open it. Claude Desktop installs the extension and runs it with its own Node.js, so nothing else is needed. The same file, under its version number, is attached to every release.

Claude Desktop (Linux beta) and manual configuration

Add the server to claude_desktop_config.json. The file may not exist yet; create it with the snippet below as its whole content, then restart Claude Desktop.

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

This needs Node.js 22 or later; see Node.js below.

Claude Code

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

To make the server available in every project, add it with user scope:

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

Cursor and other clients

Add the same mcpServers entry to the client's MCP settings. In Cursor that is ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.

Node.js

npx needs Node.js 22 or later (the Claude Desktop bundle does not). Check with node --version, and install it if needed:

• macOS (Homebrew):

  brew install node
  

• Debian and 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
  

• Other Linux distributions (nvm; open a new terminal after the first line):

  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: the same commands as Debian and Ubuntu, run inside the WSL shell.

The rest of this document is for developers and for people writing instructions for a model.

Self-hosting

The same server speaks Streamable HTTP: nbg-rates-mcp --http --port 3000 serves http://127.0.0.1:3000/mcp (add --host 0.0.0.0 to listen on every interface). On AWS Lambda the handler is dist/lambda.handler of the npm package with its production dependencies zipped beside it, behind an API Gateway HTTP API with payload format 2.0 and the $default stage (a named stage prefixes every path with its name, so each request would get a 404). Set NBG_RATES_HTTP_HOSTS to the public host name in either case, so the endpoint answers only for it.

Tools

Every tool is read-only. Dates are calendar days in Tbilisi in the form YYYY-MM-DD, and every rate is GEL per one unit of the currency. Each tool returns its result as structured content and as the same JSON in a text block.

nbg_get_rates

The official NBG rates in force on one calendar date. NBG quotes some currencies per 10, 100, 1000 or 10000 units; the rate is always divided down to one unit, and the raw pair is kept as nbgQuantity and nbgRate.

Inputs:

Output:

• requestedDate: the date asked for, or today in Tbilisi when date is omitted.
• effectiveDate: the date the returned rates took effect, as NBG publishes it.
• carriedOver: true when the rates in force on requestedDate took effect on an earlier day. They are still the official rates for requestedDate; quote effectiveDate alongside them.
• rates: one entry per currency with code, name, rate (GEL per one unit), diff (change versus the previous published rate, per one unit), nbgQuantity (the units NBG quotes the raw rate for: 1, 10, 100, 1000 or 10000) and nbgRate (the raw rate as NBG publishes it, for nbgQuantity units). Values below 0.000001, mostly the diff of a currency quoted per 1000 or 10000 units, are JSON numbers in exponent notation, for example 4e-7.
• unknownCodes: requested codes NBG did not quote on that date, and inputs that are not a three-letter currency code at all. The other requested codes are still answered. GEL is listed here too: every rate is in GEL, so the table has no row for it.

Worked example: on Monday 2026-10-05 a user asks for the AMD rate on Sunday 2026-10-04. NBG sets no rate for a Sunday, so the rate in force is the one valid from Saturday 2026-10-03, which NBG quotes as 7.1762 GEL per 1000 drams. The request

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

returns

{
  "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": []
}

The same request for Monday 2026-10-05 returns the same rate with requestedDate 2026-10-05: the rate NBG set on Friday for Saturday is still in force on Monday.

nbg_convert

Converts an amount between two currencies with the official NBG rate in force on a calendar date. Either side may be GEL; a pair without GEL is converted through GEL.

Inputs:

Output:

• amount, from, to: the request, with the codes in upper case.
• result: the converted amount, unrounded, for further calculation.
• resultRounded: the exact amount rounded half up to two decimals, computed from NBG's published figures; the amount to show. JSON drops trailing zeros, so 3.90 arrives as 3.9.
• rate: one unit of from expressed in to.
• via: direct when either side is GEL (or both codes are the same), GEL when a pair without GEL is converted through GEL.
• requestedDate, effectiveDate, carriedOver: as in nbg_get_rates.

GEL to GEL is the identity and needs no NBG rate, so it answers for any valid date. A code NBG did not quote on the date is an error.

nbg_convert_many

Converts a list of amounts, each at the official NBG rate in force on its own date: one call for a list of invoices. Items are answered independently, so a bad date or code fails only its own item. The server makes at most one NBG request per distinct date, one date after another; once NBG stops answering, the dates not yet asked fail with the same error without a request.

Inputs:

An empty list, more than 100 items, or an item without the shape { amount, from, to, date? } (a missing or non-numeric amount, a missing code, or a text over 64 characters) fails the whole call at the input schema; every other problem fails only its item.

Output:

• items: one entry per input, in input order. A converted item is the nbg_convert output, with resultRounded. A failed item is { amount, from, to, date, error }: the item as given, without date when it had none, and error, the message that says what went wrong (see Errors).
• converted, skipped: how many items were converted and how many failed.
• total: { to, resultRounded }, present only when at least one item was converted, every converted item has the same target currency, and the sum is a finite number: the sum of their resultRounded values, computed exactly, the way a ledger sums posted lines. It covers the converted items only, so it is partial when skipped is not 0.

Worked example: 10 USD and 1.5 USD to GEL on 2026-10-10, and 100 USD to GEL on 2026-13-01, a date that does not exist. The request

{
  "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" }
  ]
}

returns

{
  "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 }
}

The total, 26.01 + 3.9 = 29.91 GEL, covers the two converted items; skipped is 1, so it is partial.

nbg_list_currencies

Lists every currency NBG publishes a GEL rate for today. NBG quoted other currencies in the past, so a code missing here may still have historical rates.

Inputs:

Output:

• effectiveDate: the date today's rates took effect.
• currencies: one entry per currency with code, name and nbgQuantity (the units NBG quotes the raw rate for).

nbg_rate_history

The official rate of one currency, in GEL per one unit, in force on every calendar day of an inclusive range. One call makes one request to NBG.

Inputs:

Output:

• currency, from, to: the request, with the code in upper case.
• days: one entry per calendar day. A day whose own rate is in force is { date, rate }, with rate in GEL per one unit. A carried-over day adds effectiveDate, the day its rate took effect, and carriedOver: true; an absent effectiveDate means the rate took effect on date itself. A full year stays near 6,000 tokens.
• summary: first, last, change (last minus first), min and max with minDate and maxDate (first occurrence), and average, the arithmetic mean over every calendar day of the range, carried-over days included. change and average are exact, rounded half up to the decimals NBG's quantity gives the currency, 4 + log10(nbgQuantity), the largest over the days (4 for USD, 7 for AMD).

For example, USD from Friday 2026-10-02 to Tuesday 2026-10-06 (Saturday has its own rate; Sunday and Monday carry it):

{
  "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
  }
}

A range that reaches a date NBG has not published yet is an error, as is a day in the range for which NBG's export has no rate of the currency (for example before NBG first quoted it, or after NBG stopped).

Resource nbg://rates/{date}

The full official NBG rate table in force on a calendar date (YYYY-MM-DD) or on today, as JSON with the same fields as the nbg_get_rates output and English currency names. nbg://rates/today is listed among the server's resources.

Errors

A tool that cannot answer returns an error result whose text says what went wrong and what to do next:

• the date is not a real calendar date in the form YYYY-MM-DD, or a history range ends before it starts;
• a history range is longer than 366 days;
• the currency is not a three-letter code (the message names USD, EUR and GEL as examples), or NBG did not quote it on the requested date or range (nbg_get_rates lists such codes in unknownCodes instead); NBG has added and dropped currencies over the years, so the code may still have rates on other dates;
• a conversion result is too large to represent as a number;
• NBG has no rate in force on the date (the archive starts on 1995-10-14, and a currency has no rate before NBG first quoted it, after NBG stopped quoting it, or where NBG's records have a gap);
• NBG has not published a rate for the date yet; the message names today in Tbilisi, says that tomorrow is the furthest date that can have a rate and only once NBG has published it, and, when known, names the date from which the latest published rate is valid. A history range that reaches such a date fails as a whole: end it at today;
• NBG did not respond usably; the request can be retried;
• the NBG response did not have the expected shape, which means the NBG endpoint may have changed; please open an issue with the package version.

Reading the resource fails with the same messages.

Date rules

• NBG sets a rate on business days around 17:00 Tbilisi time, valid from the next calendar day until the next rate. Once it is published, tomorrow's rate can be requested by date.
• "Today" means the calendar date in Tbilisi, wherever the client runs.
• Sundays, Mondays and days after a public holiday have no rate of their own: they carry the earlier rate with carriedOver: true and effectiveDate set to the day it took effect. Before September 2021 NBG stored a rate for every calendar day, so older Sundays are not carried over.
• A date whose rate NBG has not published yet (tomorrow before about 17:00 Tbilisi time, or any later date) returns an error, never a guess.
• NBG occasionally publishes a table for a day after that day: on Monday 2026-09-28 at 17:01 it published the table valid from Saturday 2026-09-26, which replaced Friday's rate for 2026-09-26 to 2026-09-28. A carried-over answer for the last seven days can therefore change; the server asks NBG again after ten minutes for those, and after twelve hours for every other answer.
• The archive starts on 1995-10-14 with USD; other currencies start later.

Environment variables

Set them in the client's configuration, for example:

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

Development

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

Before a pull request, also run npm run format:check, npm run lint and npm run typecheck.

The code is split into src/core, pure functions with no I/O (date rules, parsing, per-unit normalisation, conversion, history), and src/shell, which holds the effects (the NBG HTTP client, the cache, the rates service and the MCP server). src/bin.ts is the executable.

The repository's rulesets (protection of main, and release tags that only admins may create) are defined in .github/rulesets/ and applied with scripts/apply-rulesets.sh; its description, homepage and topics are defined in .github/repository.json and applied with scripts/apply-repo-settings.sh. Both are run by a maintainer after a change, never edited in the GitHub UI.

License

MIT, see LICENSE.