MCP 服务器

nbp-mcp

Local MCP server for the Polish National Bank (NBP) public API enabling exchange rates, gold prices, and currency conversion without authentication.

README

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 does the right thing: fetches the mid-rate for the last publication date before that, computes, returns.

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

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. 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: twice-weekly 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/nbp-mcp.git
cd nbp-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

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 1240.50 EUR to PLN using the rate from 2026-07-15."

convert(amount=1240.50, from_currency="EUR", rate_date="2026-07-15") → PLN amount, the rate used, and the effective date NBP actually published. Polish tax law: use the last business day before the invoice date; pass that date to rate_date, not the invoice date itself.

"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 invoice in PLN is the rate published on the last business day before the invoice date (art. 24 pkt 8 CIT/PIT). Not the invoice date itself. This is a common source of manual mistakes. convert(..., rate_date="YYYY-MM-DD") asks NBP for that specific date — if NBP didn't publish that day, the response tells you and you retry with the prior day.

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.