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.

nbg-rates.env.ge: what it does and how to add it, in English and Georgian.

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 open chatgpt.com/plugins, select the plus button, then "Add custom MCP server", paste the URL under Connection, leave authentication off and finish with "Create as a plugin" (in a workspace, an admin may need to allow custom MCP servers first). The landing page, nbg-rates.env.ge, has step-by-step instructions for each app.

This hosted service is the latest release of this server, run by the maintainer on AWS. It needs no account and never records the amounts or currencies asked; for a past date it keeps a copy of NBG's table the first time anyone asks, and the copy does not say who asked or when. It keeps two logs for 30 days: which tool was called from which client and whether NBG answered, 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). The logs are used only to keep the service running, to see which clients use it and to investigate errors or abuse; they are not sold, shared or used for advertising. The landing page sets no cookies and loads nothing from anyone else.

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.

| Platform | Location of 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"] } } }

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. Optionally, NBG_RATES_MIRROR_TABLE names a DynamoDB table that the same function fills from NBG on a schedule and then answers from; unset, lookups go to NBG as before.

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:

| Name | Required | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | date | no | Calendar date. Defaults to today in Tbilisi. Tomorrow's rate exists after about 17:00 Tbilisi time. | | currencies | no | ISO 4217 codes to return, case-insensitive, duplicates ignored, for example ["USD", "EUR"]. When given, the list holds at least one entry. Omit for all currencies. | | language | no | Language of the currency names: en (default) or ka (Georgian). Codes, numbers and dates are the same in both. |

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:

| Name | Required | Description | | -------- | -------- | ------------------------------------------------------------------------- | | amount | yes | Amount in the from currency. A finite number, may be negative. | | from | yes | ISO 4217 code, or GEL. | | to | yes | ISO 4217 code, or GEL. | | date | no | Calendar date whose official rate to apply. Defaults to today in Tbilisi. |

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_