nbp-mcp
Query the Polish National Bank (NBP) public API for exchange rates and gold fixings, and convert amounts for Polish bookkeeping — locally via MCP, no authentication required.
Get a single currency's NBP exchange rate vs PLN on a specific date or the latest available (Tables A, B, or C).
List all currency rates from an NBP table for a date or the latest published table.
Retrieve exchange-rate history for one currency over a date range of up to 367 days.
Get the NBP gold fixing (PLN per gram of 1000-fineness gold) on a date or the latest.
Retrieve gold fixing history over a date range of up to 367 days.
Convert an amount between currencies using NBP mid-rate (Table A, falling back to B), defaulting the target to PLN, and return the amount, rate used, and effective date.
Choose tables A/B/C to distinguish accounting mid-rates from actual FX bid/ask rates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nbp-mcp convert 1240.50 EUR to PLN using the rate from 2026-07-15"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.txtOn 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.pyClaude 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.
GitHub: https://github.com/bartosz-kuc
Email: firma@bartosza.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.
Related
honest-gmail-mcp — local Gmail MCP
honest-calendar-mcp — local Google Calendar MCP
honest-drive-mcp — local Google Drive MCP with permission management
honest-nip-krs-mcp — Polish company registry MCP (biała lista + KRS)
Available Tools
6 toolsconvertA
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
Scored across 6 tools
Each tool has a distinct purpose: getting single rates, rate history, gold price, gold history, listing all rates, and conversion. No overlap in functionality.
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.
With 6 tools, the server is well-scoped for an NBP exchange rate API, covering core operations without being too many or too few.
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
Related MCP Connectors
A MCP server for the Frankfurter API for currency exchange rates.
Official Polish central bank (NBP) exchange rates, currency conversion and gold prices.
Unofficial Frankfurter MCP — wraps Frankfurter API (api.frankfurter.dev)
Related MCP Servers
- FlicenseBqualityDmaintenanceAn 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-
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that simulates financial data interactions with dummy authentication and static JSON datasets for testing financial applications.2MIT
- -licenseNot gradedqualityNot gradedmaintenanceMCP server that provides real exchange-rate data from the European Central Bank, including latest rates, currency conversion, historical rates, and time series.-
- AlicenseAqualityDmaintenanceMCP 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.511 npmMIT