@m8t-jacob/mcp-polish-biz

An MCP (Model Context Protocol) server that gives AI agents — Claude Desktop, Claude Code, Cursor, or any other MCP client — direct access to Polish business data: identifier validation, the VAT whitelist, EU VIES lookups, and NBP exchange rates.

It's a thin wiring layer: every tool delegates to a small, independently published, fully-tested package — @m8t-jacob/validate, @m8t-jacob/polish-registry, and @m8t-jacob/pln-utils — so this repo contains no domain logic of its own, just MCP tool definitions, zod input schemas, and error mapping.

• Built on the official @modelcontextprotocol/sdk McpServer API
• Runs over stdio — the transport used when an MCP client launches a server as a local subprocess (typically via npx)
• Every tool validates its input with zod and never throws: failures come back as a normal tool result with isError: true, so one bad call can't crash the server
• Strict TypeScript, ships dual ESM + CJS builds with .d.ts
• 100% test coverage on tool handlers — dependencies are mocked, so the test suite makes zero real network calls

Install for Claude Desktop / Claude Code

Add this to your MCP client's configuration (for Claude Desktop, claude_desktop_config.json; for Claude Code, .mcp.json or via claude mcp add):

{
  "mcpServers": {
    "polish-biz": {
      "command": "npx",
      "args": ["-y", "@m8t-jacob/mcp-polish-biz"]
    }
  }
}

No API key or configuration is required — every underlying API (the VAT whitelist, VIES, and NBP) is free and public.

You can also run it directly to smoke-test it:

npx -y @m8t-jacob/mcp-polish-biz

It will sit waiting for JSON-RPC requests on stdin — that's expected; it's meant to be driven by an MCP client, not used interactively.

Tools

| Tool | Description | Backed by | | ---------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------- | | validate_polish_id | Validate a NIP, PESEL, REGON, KRS, or IBAN/NRB and return its normalized form. Offline, no network. | @m8t-jacob/validate | | check_vat_whitelist | Look up a NIP on the Polish VAT whitelist ("Biała lista podatników VAT"): status, name, accounts. | @m8t-jacob/polish-registry | | check_vies | Validate an EU VAT number via VIES, returning company name/address when available. | @m8t-jacob/polish-registry | | get_exchange_rate | Get the official NBP mid exchange rate for a currency against PLN, for today or a given date. | @m8t-jacob/pln-utils | | convert_currency | Convert an amount between two currencies using NBP mid rates. | @m8t-jacob/pln-utils |

validate_polish_id

{ "type": "nip", "value": "PL 526-000-12-46" }

{ "valid": true, "type": "nip", "normalized": "5260001246" }

type is one of nip, pesel, regon, krs, iban.

check_vat_whitelist

{ "nip": "5252445767", "date": "2026-07-13" }

Returns the WhitelistResult shape from @m8t-jacob/polish-registry (name, statusVat, regon, krs, accountNumbers, found, ...). date is optional (YYYY-MM-DD, defaults to today).

check_vies

{ "countryCode": "PL", "vatNumber": "5252445767" }

Returns the ViesResult shape (valid, name?, address?, countryCode, vatNumber, requestDate).

get_exchange_rate

{ "code": "USD", "date": "2025-01-15" }

Returns { code, rate, date, table }. date is optional.

convert_currency

{ "amount": 100, "from": "USD", "to": "EUR" }

Returns { amount, from, to, result, date? }. date is optional and, when given, is used for both legs of the conversion.

Programmatic use

The server can also be embedded directly, without going through stdio — useful for tests or for hosting it behind a different transport:

import { createServer, TOOLS } from '@m8t-jacob/mcp-polish-biz';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer();
await server.connect(new StdioServerTransport());

TOOLS (also exported) is the array of { name, description, inputSchema, handler } this server registers — each handler can be called directly in tests without any transport, see examples/basic.ts.

🇵🇱 Po polsku

@m8t-jacob/mcp-polish-biz to serwer MCP (Model Context Protocol) dający agentom AI (Claude Desktop, Claude Code, Cursor) dostęp do polskich danych biznesowych: walidacji NIP/PESEL/REGON/KRS/IBAN, Białej listy podatników VAT, unijnego systemu VIES oraz kursów walut NBP. Cała logika domenowa pochodzi z trzech niezależnie opublikowanych pakietów (@m8t-jacob/validate, @m8t-jacob/polish-registry, @m8t-jacob/pln-utils) — ten serwer jest wyłącznie cienką warstwą narzędzi MCP nad nimi. Każde narzędzie waliduje dane wejściowe przez zod i nigdy nie rzuca wyjątku — błąd wraca jako zwykły wynik z isError: true, więc jedno nieudane wywołanie nie może zatrzymać całego serwera. Instalacja nie wymaga żadnego klucza API — wszystkie API źródłowe (Biała lista, VIES, NBP) są darmowe i publiczne.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development workflow and GOOD_FIRST_ISSUES.md for ideas if you're looking for a place to start. This project follows the Contributor Covenant.

License

MIT © 2026 Jakub Jagiełło