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 汇率是多少？
• 按照 NBG 2026 年 9 月 27 日的汇率，将 1,500 USD 换算为 GEL。
• 列出 2026 年 9 月每天的 EUR 汇率，并以表格呈现。
• 按照 NBG 汇率，今天 1 欧元能兑换多少美元？

请将月份写成文字，例如“2026 年 9 月 10 日”：10/09/2026 可能被解读为两个不同的日期。

对于第二个问题，答案是：2026 年 9 月 27 日是星期日，因此适用的汇率是 NBG 为 9 月 26 日星期六设定的汇率，即 1 USD 兑换 2.6080 GEL；该汇率在星期日仍然有效。1,500 USD = 3,912.00 GEL，答案还会说明该汇率沿用自 26 日。

在 Claude Desktop 中，聊天的“+”菜单也会列出此服务的四个现成问题：今天的汇率、指定日期的汇率、金额换算，以及某月的汇率表。

你获取的汇率

格鲁吉亚的会计和税务申报使用交易日期当天生效的 NBG 官方汇率。本服务返回的正是该汇率，也就是你指定日期在 nbg.gov.ge 上显示的汇率。

换算金额会按照账簿入账方式四舍五入到小数点后两位（resultRounded），并根据 NBG 公布的数据精确计算。

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 天：从哪个客户端调用了哪个工具，以及 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，或添加到某个项目内的 .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；运行第一行后，请打开新终端）：

  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 shell 中运行。

本文档其余部分面向开发者，以及为模型编写说明的人。

自托管

同一服务支持 Streamable HTTP：运行 nbg-rates-mcp --http --port 3000 会在 http://127.0.0.1:3000/mcp 提供服务（添加 --host 0.0.0.0 可监听所有网络接口）。在 AWS Lambda 上，处理程序是 npm 包中的 dist/lambda.handler，其生产依赖项需与处理程序一起打包成 zip，并部署在使用 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"]。指定时，列表至少包含一项。省略则返回所有货币。
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（NBG 公布的原始汇率，适用于 nbgQuantity 个单位）。小于 0.000001 的值（主要是按 1000 或 10000 个单位报价的货币的 diff）会以指数记数法表示为 JSON 数字，例如 4e-7。
• unknownCodes：请求的代码中，NBG 在该日期未报价的代码，以及并非三字母货币代码的输入。其他请求的代码仍会返回结果。GEL 也会列在此处：所有汇率均以 GEL 计价，因此表中没有 GEL 对应的行。

示例：星期一 2026-10-05，用户查询星期日 2026-10-04 的 AMD 汇率。NBG 星期日不设汇率，因此当时生效的汇率是自星期六 2026-10-03 起有效的汇率，即每 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 官方汇率，在两种货币之间换算金额。任一方都可以是 GEL；不含 GEL 的货币对会通过 GEL 换算。

输入：

名称	必填	说明
amount	是	from 货币的金额。必须是有限数值，可以为负数。
from	是	ISO 4217 代码或 GEL。
to	是	ISO 4217 代码或 GEL。
date	否	要应用官方汇率的日历日期。默认为第比利斯当天的日期。

输出：

• amount、from、to：请求中的值，货币代码为大写。
• result：未舍入的换算金额，供后续计算使用。
• resultRounded：根据 NBG 公布的数据计算，并按四舍五入规则精确保留两位小数的金额，即要显示的金额。JSON 会去掉末尾的零，因此 3.90 会以 3.9 返回。
• rate：1 单位 from 货币折合的 to 货币金额。
• via：任一方为 GEL（或两个代码相同）时为 direct；不含 GEL 的货币对通过 GEL 换算时为 GEL。
• requestedDate、effectiveDate、carriedOver：含义同 nbg_get_rates。

GEL 兑换 GEL 是恒等换算，无需 NBG 汇率，因此任何有效日期都可以查询。如果 NBG 在指定日期未公布某货币的汇率，则会报错。

nbg_convert_many

按每个金额各自日期有效的 NBG 官方汇率换算金额列表：一次调用即可处理一组发票。各项独立处理，因此日期或代码无效只会导致对应项失败。服务对每个不同日期最多向 NBG 请求一次，并逐个日期请求；一旦 NBG 停止响应，尚未请求的日期会在不发起请求的情况下返回相同错误。

输入：

名称	必填	说明
items	是	1 到 100 个 { amount, from, to, date? } 条目，每项遵循 nbg_convert 的规则。

空列表、超过 100 个条目，或形状不符合 { amount, from, to, date? } 的条目（缺少金额、金额不是数值、缺少代码，或文本超过 64 个字符）会导致整个调用在输入架构校验阶段失败；其他问题只会导致对应条目失败。

输出：

• items：每个输入对应一个条目，顺序与输入一致。已换算的条目为 nbg_convert 的输出，包含 resultRounded。失败的条目为 { amount, from, to, date, error }：包含原样提供的条目；如果未提供 date，则不包含该字段；error 是说明问题所在的消息（参见错误）。
• converted、skipped：已换算和失败的条目数。
• total：{ to, resultRounded }。仅当至少有一个条目已换算、所有已换算条目的目标货币相同，且总和为有限数值时才会提供。该值是已换算条目的 resultRounded 之和，精确计算，方式与账簿汇总已入账项目相同。它只统计已换算的条目，因此当 skipped 不为 0 时，该总额为部分总额。

示例：10 USD 和 1.5 USD 在 2026-10-10 换算为 GEL，100 USD 在 2026-13-01 换算为 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，涵盖两项已换算的条目；skipped 为 1，因此这是部分总额。

nbg_list_currencies

列出 NBG 今日公布 GEL 汇率的所有货币。NBG 过去曾报价其他货币，因此此处缺少的代码仍可能有历史汇率。

输入：

名称	必填	描述
language	否	货币名称的语言：en（默认）或 ka（格鲁吉亚语）。

输出：

• effectiveDate：今日汇率生效的日期。
• currencies：每种货币对应一个条目，包含 code、name 和 nbgQuantity（NBG 报价原始汇率时使用的单位数）。

nbg_rate_history

某种货币在包含首尾日期的日期范围内每个日历日生效的官方汇率，单位为每 1 个单位对应的 GEL。每次调用都会向 NBG 发出一个请求。

输入：

名称	必填	描述
currency	是	ISO 4217 代码，例如 USD。
from	是	范围内的首个日历日，包含该日。
to	是	范围内的最后一个日历日，包含该日。最多 366 天，包含 from。

输出：

• currency、from、to：请求中的值，货币代码为大写。
• days：每个日历日对应一个条目。某日当天生效的汇率表示为 { date, rate }，其中 rate 的单位为每 1 个单位对应的 GEL。沿用前一汇率的日期还会包含 effectiveDate（该汇率生效的日期）和 carriedOver: true；若没有 effectiveDate，则表示汇率在 date 当天生效。完整一年的数据约占 6,000 个 token。
• summary：包含 first、last、change（最后值减去首值）、min 和 max（分别带有 minDate 和 maxDate，取首次出现的日期），以及 average，即该范围内每个日历日的算术平均值，包括沿用前一汇率的日期。change 和 average 均按 NBG 对该货币报价所用的小数位数进行四舍五入（逢五进一），该位数为 4 + log10(nbgQuantity)，取日期范围内的最大值（USD 为 4，AMD 为 7）。

例如，USD 从星期五 2026-10-02 到星期二 2026-10-06（星期六有自己的汇率；星期日和星期一沿用该汇率）：

{
  "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 停止报价的日期），也会报错。

资源 nbg://rates/{date}

指定日历日期（YYYY-MM-DD）或 today 生效的完整 NBG 官方汇率表，以 JSON 格式提供，字段与 nbg_get_rates 输出相同，货币名称为英文。nbg://rates/today 列于服务的资源列表中。

错误

无法回答的工具会返回错误结果，其中的文本会说明出错原因和后续操作：

• 日期不是符合 YYYY-MM-DD 格式的有效日历日期，或历史记录范围的结束日期早于开始日期；
• 历史记录范围超过 366 天；
• 货币不是三字母代码（错误消息会列出 USD、EUR 和 GEL 作为示例），或 NBG 未在请求的日期或范围内为其报价（nbg_get_rates 会在 unknownCodes 中列出此类代码）；NBG 多年来增删过货币，因此该代码在其他日期仍可能有汇率；
• 换算结果过大，无法表示为数字；
• NBG 在该日期没有生效汇率（档案始于 1995-10-14；在 NBG 首次为某种货币报价之前、停止报价之后，或 NBG 记录存在缺漏之处，该货币均没有汇率）；
• NBG 尚未发布该日期的汇率；错误消息会指出第比利斯的今天日期，说明明天是可能有汇率的最远日期，且只有在 NBG 发布汇率后才可以查询；如果已知，还会指出最新已发布汇率的生效日期。若历史记录范围包含此类日期，整个请求都会失败：请将结束日期设为今天；
• NBG 未返回可用响应；可以重试请求；
• NBG 响应的结构与预期不符，这意味着 NBG 端点可能已变更；请附上软件包版本提交问题。

读取资源失败时也会返回相同的错误消息。

日期规则

• 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 的星期五汇率。因此，最近七天的沿用汇率答案可能会变化；服务会在十分钟后再次向 NBG 查询这些日期的汇率，并在十二小时后重新查询其他所有答案。
• 汇率档案始于 1995-10-14，最初只有 USD；其他货币的记录始于更晚日期。

环境变量

变量	作用
NBG_RATES_BASE_URL	要调用的 NBG 主机。默认为 https://nbg.gov.ge；末尾的斜杠会被移除。适用于测试。
NBG_RATES_DEBUG	设为 1 可将每个上游请求记录到 stderr。请在错误报告中附上此日志。
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。