Skip to main content
Glama

honest-nbp-mcp

Local MCP server for the Polish National Bank (NBP) public API — exchange rates and gold fixing, no authentication required.

Part of the honest-mcp family of small, auditable, local-first MCP servers.

Why

Every Polish JDG owner receiving a foreign-currency invoice has to convert it to PLN using the NBP mid-rate from the last business day before the invoice date — that's what the tax code requires. Today that's a manual look-up in a browser tab, once per invoice, every month.

This server puts the NBP API a single tool call away. Ask your AI "convert 500 EUR from an invoice dated 2026-07-15 to PLN" and it can call convert with before_date="2026-07-15": the server takes the mid-rate from the last table NBP published before that date, computes, returns.

Same trust model as the rest of the family: data flows only between your machine and NBP.

Related MCP server: Local Financial MCP Mock Server

Features

Six tools:

  • get_rate — NBP exchange rate for one currency on a date (or latest). Tables A / B / C.

  • list_rates — the whole table on a date (or latest).

  • get_rate_history — rate history for a currency over a date range (≤367 days).

  • get_gold — gold fixing (PLN per gram of 1000-fineness) on a date (or latest).

  • get_gold_history — gold history over a date range.

  • convert — convert an amount between two currencies using NBP mid-rate, either on an exact date (rate_date) or from the last table published before a date (before_date, e.g. the invoice date). Handles PLN as either side, cross-rates via PLN, Table A/B fallback for exotic currencies.

Data source

  • Endpoint: api.nbp.pl — the National Bank of Poland's public REST API

  • No API key, no registration, no rate limit

  • Table A: daily mid-rate for major currencies (USD, EUR, GBP, CHF, JPY, …) — this is what accounting uses

  • Table B: weekly (Wednesday) rates for less common currencies

  • Table C: daily bid/ask spread — use for actual FX transactions, not bookkeeping

Requirements

  • Python 3.10+

Setup

git clone https://github.com/bartosz-kuc/honest-nbp-mcp.git
cd honest-nbp-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

On Windows, use venv\Scripts\pip and venv\Scripts\python instead of venv/bin/pip and venv/bin/python (here and in the configs below).

Register with Claude Code:

claude mcp add nbp /absolute/path/to/venv/bin/python /absolute/path/to/server.py

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "nbp": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Example usage

"What was the NBP mid-rate for USD on 2026-03-14?"

get_rate(currency="USD", date="2026-03-14") → mid rate + effective date. If NBP didn't publish on that day (weekend/holiday) the server returns a clear 404 payload so the caller knows to try the previous business day.

"Convert a 1240.50 EUR invoice dated 2026-07-15 to PLN."

convert(amount=1240.50, from_currency="EUR", before_date="2026-07-15") → PLN amount, the rate used, and the effective date of the NBP table it came from — the last table published strictly before 2026-07-15 (looked up over the preceding 14 days).

convert(..., rate_date="2026-07-15") instead uses the table published on exactly that date; on weekends/holidays it returns an error payload (NBP has no table for that day). rate_date and before_date cannot be combined.

"How has EUR/PLN moved this quarter?"

get_rate_history(currency="EUR", start_date="2026-04-01", end_date="2026-06-30") → full daily series.

Data flow

Your AI client
     ↕  MCP stdio
This server (Python, on your machine)
     ↕  HTTPS
api.nbp.pl (National Bank of Poland)

No cloud middle. Nothing to log in to. No telemetry.

For Polish accountants and JDG owners

The important bit for księgowość: the NBP mid-rate you use to book a foreign-currency amount in PLN is the rate published on the last business day before the day the revenue is earned or the cost incurred — for most invoices, the business day before the invoice or delivery date (art. 11a ust. 1–2 ustawy o PIT; in the CIT act art. 12 ust. 2 and art. 15 ust. 1). Not that day's own rate. This is a common source of manual mistakes. convert(..., before_date="YYYY-MM-DD") with the invoice date does the look-back for you and returns the effective date of the table it used, so you can record it. convert(..., rate_date="YYYY-MM-DD") asks NBP for that exact date only — if NBP didn't publish that day, the response says so.

Author

Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.

Consulting

Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.

License

MIT — see LICENSE.

Available Tools

6 tools
convertA

Convert an amount from one currency to another using NBP mid-rate (Table A, or B if not in A). Primary use case: converting a foreign-currency invoice to PLN for Polish bookkeeping. Polish tax law requires using the NBP mid-rate from the last business day BEFORE the invoice date — pass that date as rate_date, not the invoice date itself. Returns the amount, the rate used, and the effective date.

Inputs: amount (required), from_currency (required), rate_date, to_currency.

get_goldA

Get the NBP gold fixing (cena złota) in PLN per gram of 1000-fineness gold, on a specific date or the latest. Published daily on business days.

Inputs: date.

get_gold_historyA

Get NBP gold fixing history over a date range. Range must be at most 367 days per NBP API limits.

Inputs: end_date (required), start_date (required).

get_rateA

Get the NBP exchange rate for a single currency vs PLN, on a specific date or the latest available. Table A = daily rates for major currencies (USD, EUR, GBP, CHF, JPY, etc.). Table B = twice-weekly rates for less common currencies. Table C = daily buy/sell rates (bid/ask) for major currencies — use for actual FX transactions, not accounting. For invoice-to-PLN conversion in Polish bookkeeping, use Table A. Note: NBP does not publish on weekends/holidays.

Inputs: currency (required), date, table.

get_rate_historyA

Get the NBP exchange rate history for a currency over a date range. Range must be at most 367 days per NBP API limits.

Inputs: currency (required), end_date (required), start_date (required), table.

list_ratesA

List all currency rates from an NBP table on a given date (or latest). Useful for seeing what's available and comparing multiple currencies at once.

Inputs: date, table.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: getting single rates, rate history, gold price, gold history, listing all rates, and conversion. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_rate, list_rates, convert, etc.), making them predictable and easy to remember.

    Tool Count5/5

    With 6 tools, the server is well-scoped for an NBP exchange rate API, covering core operations without being too many or too few.

    Completeness4/5

    The tool set covers getting current and historical rates, gold prices, listing all rates, and conversion. Minor gap: no explicit tool for bid/ask rates, but get_rate with Table C can retrieve them.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      An MCP server that provides currency rates, conversions, and historical exchange-rate data using the Frankfurter API. It enables users to retrieve latest rates, convert amounts between currencies, and access time-series data for currency pairs.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight MCP server that simulates financial data interactions with dummy authentication and static JSON datasets for testing financial applications.
      2
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      MCP server that provides real exchange-rate data from the European Central Bank, including latest rates, currency conversion, historical rates, and time series.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that provides AI agents with Polish business data tools: identifier validation (NIP, PESEL, REGON, KRS, IBAN), VAT whitelist checks, EU VIES lookups, and NBP exchange rates.
      5
      11 npm
      MIT