nbg-rates-mcp

# 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](https://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:

```text
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](https://github.com/akalongman/nbg-rates-mcp/releases/latest/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](https://github.com/akalongman/nbg-rates-mcp/releases).

### 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/`                      |

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

This needs Node.js 22 or later; see [Node.js](#nodejs) below.

### Claude Code

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

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

```bash
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):

  ```bash
  brew install node
  ```

- Debian and Ubuntu (NodeSource, Node.js 24):

  ```bash
  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):

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

- Windows (PowerShell):

  ```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:

| 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

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

returns

```json
{
  "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, ma