skanfirmy.pl

io.github.bartosz-kucPublished by GitHub account bartosz-kucv1.4.0Updated Oct 30, 2026

Verify Polish companies by NIP/KRS/REGON + EU VAT (VIES). 14 MCP tools (9 no-key).

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingFinanceBusiness & Commerce

Overview

AI-generated overview

Remote MCP server for verifying Polish companies by NIP, KRS and REGON, validating EU VAT numbers, and optionally monitoring registry changes.

What you can do
  • Look up a Polish company's VAT status and KRS data by NIP, or bulk-check up to 30 NIPs at once
  • Fetch REGON registry data and validate EU VAT numbers through VIES
  • Check whether a bank account appears on the VAT White List for a NIP, and generate an individual tax micro-account
  • Search PKD 2025 activity codes and calculate statutory or B2B late-payment interest
  • Search a catalog of public Polish and EU APIs
  • Monitor NIPs for VAT, bank-account or registry changes, list watches, fetch changes since a date, and set a signed webhook
When to use it
Useful when an assistant needs to check a Polish contractor's VAT or registry status, confirm a bank account before a payment, validate an EU VAT number, or keep an eye on counterparty changes over time.
Requirements
Remote Streamable HTTP endpoint; no key or registration for the nine lookup and calculator tools. The five monitoring tools need a skanfirmy API key obtained after confirming a sign-up. Stdio-only clients need a bridge such as mcp-remote. Per-IP rate limits apply.
Before you install
Lookups send NIP and VAT numbers to a third-party service that queries government registers; data for natural persons is minimised under GDPR and some numbers are restricted from presentation. Monitoring tools write data: observe_nip and unobserve_nip add or delete watches, and set_webhook returns a signing secret only once and sends change notifications to the URL you supply. The API key is a credential to protect.

Installation

In SourceWeft

  1. Open skanfirmy.pl in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.bartosz-kuc%2Fskanfirmy/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "skanfirmy-pl": {
      "type": "http",
      "url": "https://skanfirmy.pl/mcp"
    }
  }
}

README

skanfirmy.pl — MCP server

A free, stateless MCP (Model Context Protocol) server that lets AI agents verify Polish companies and validate EU VAT numbers directly from official government registers. No key and no registration for the lookups; per-IP rate limits apply (see Limits and personal data).

  • Endpoint: https://skanfirmy.pl/mcp (JSON-RPC 2.0 over Streamable HTTP)
  • 14 tools: 9 lookups and calculators combining the VAT Register (Ministry of Finance), KRS (Ministry of Justice), REGON (Statistics Poland / GUS) and VIES (European Commission), plus 5 tools for the optional change monitoring, which need an API key.
  • Also usable as plain REST for crawlers/agents that can't speak MCP.

Made by Bartosz Kuć — the same person behind skanfirmy.pl and the otwarteAPI.pl catalog of Polish & EU public APIs.

Tools

ToolWhat it does
sprawdz_nipVAT status (Biała Lista) + KRS data for a company by NIP
sprawdz_lista_nipBulk lookup of up to 30 NIPs in one call (MF VAT Register)
sprawdz_regonREGON registry data (GUS) by NIP; for sole traders and other natural persons only name, legal form, entity type, town and activity status
sprawdz_viesValidate an EU VAT number via VIES (European Commission)
sprawdz_rachunekIs a bank account on the VAT White List for a given NIP
generuj_mikrorachunekIndividual tax micro-account (PIT/CIT/VAT) from a NIP; the formula for a PESEL is in the tool description, to compute locally
szukaj_pkdSearch the PKD 2025 business-activity classification
oblicz_odsetkiStatutory / commercial (B2B) late-payment interest calculator
szukaj_katalog_apiSearch otwarteAPI.pl — a catalog of other public PL/EU APIs

Monitoring tools (need a skanfirmy API key, which you get after confirming a sign-up at skanfirmy.pl/monitoring): observe_nip, unobserve_nip, list_observations, changes_since, set_webhook.

Limits and personal data

  • Rate limits per IP address. MCP: at most 60 requests per 10 seconds, then HTTP 429 with a JSON-RPC error (error.data.contact) for 10 seconds. REST endpoints: at most 20 requests per 10 seconds, then HTTP 429 for 10 seconds. The service is meant for single lookups started by users or their agents, not for bulk data harvesting.
  • Source limits. The Ministry of Finance White List API has its own daily limits (search: 100 queries a day, up to 30 NIPs each), shared by all users of the service. When they run out, lookups answer HTTP 503 until the next day.
  • Sole traders and other natural persons (entities without a KRS number, and civil partnerships) get minimised data (GDPR): name, NIP, VAT status, town and the number of White List accounts. No REGON number, address, registration date, PKD codes or list of account numbers. To check one specific account, use sprawdz_rachunek (REST: POST /rachunek).
  • Numbers restricted from presentation. Data for some numbers is not presented (a data-protection procedure). The answer is then restricted: true with a fixed sentence and a link to the Ministry of Finance search, with no data and no fields about validity, VAT status or presence in the register. Send the user to the official search.

Connect

Any MCP client that supports remote (Streamable HTTP) servers — point it at:

https://skanfirmy.pl/mcp

Claude Desktop / stdio-only clients — bridge with mcp-remote:

json
{  "mcpServers": {    "skanfirmy": {      "command": "npx",      "args": ["-y", "mcp-remote", "https://skanfirmy.pl/mcp"]    }  }}

Raw JSON-RPC (no MCP client needed):

bash
# list toolscurl -s https://skanfirmy.pl/mcp \  -H 'Content-Type: application/json' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# check a company by NIPcurl -s https://skanfirmy.pl/mcp \  -H 'Content-Type: application/json' \  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sprawdz_nip","arguments":{"nip":"5261040828"}}}'

Plain REST (no MCP)

For agents/crawlers that just want a URL:

  • GET https://skanfirmy.pl/nip/{nip} — VAT + KRS
  • GET https://skanfirmy.pl/nips/{comma,separated,nips} — bulk (≤30)
  • GET https://skanfirmy.pl/regon/{nip} — REGON registry data
  • GET https://skanfirmy.pl/vies/{country}/{number} — EU VAT (VIES)
  • POST https://skanfirmy.pl/rachunek — is one bank account on the White List for a NIP

Add ?format=json for JSON. Full docs: skanfirmy.pl/llms.txt, OpenAPI: skanfirmy.pl/openapi.yaml.

Claude Agent Skill

Prefer a drop-in Agent Skill? skill/ holds verify-polish-company — a single SKILL.md that teaches Claude Code, the Claude apps or the Agent SDK when and how to call the endpoints above (no key, nothing to run beyond ordinary HTTP):

bash
cp -R skill ~/.claude/skills/verify-polish-company

See skill/README.md for details.

Data sources

VAT Register / Biała Lista (Ministry of Finance), KRS (Ministry of Justice), REGON / BIR (Statistics Poland — GUS), VIES (European Commission). Independent project — not affiliated with any of them. What the service stores and for how long is described in its privacy policy.

Author

Bartosz Kuć · skanfirmy.pl · github.com/bartosz-kuc · linkedin.com/in/bartosz-kuc · cal.com/bartosz-kuc

License

MIT © Bartosz Kuć. This repository documents the hosted server and holds its MCP registry manifest; the server itself runs at https://skanfirmy.pl/mcp.

Source: README.md at commit a9d0ebb

Tools

14

sprawdz_nip

Check VAT status (VAT White List / Biała Lista) and KRS data for a Polish company by NIP. For entities without a KRS number (sole proprietors and civil partnerships, i.e. natural persons) personal data is limited (GDPR): the address is reduced to the town (the White List does not say whether it is a business or a home address), and bank accounts to their count — check a specific account with sprawdz_rachunek; no REGON number, registration date or PKD codes are returned for them (the ceidg field is always null). The privacy field lists what was hidden. White List data for entities with a KRS number may come from a same-day cache: then mfCached is true and bl.mfRequestDateTime is the time of the original Ministry query.

Parametersniprequired

sprawdz_lista_nip

Bulk-check up to 30 NIPs in one call to the Ministry of Finance VAT White List: VAT status, bank accounts, REGON, KRS number and address of each entity. For entities without a KRS number (natural persons) the address is reduced to the town and bank accounts to their count, and no REGON number or registration date is returned (GDPR) — check a specific account with sprawdz_rachunek. For verifying a portfolio of counterparties. Ministry limits: max 30 NIPs per call; the Ministry's daily query limit is shared by the whole service — when it is exhausted, the tool returns an error. Does not fetch full KRS data (use sprawdz_nip for individual entities). If every NIP in the list is an entity with a KRS number already checked today, the result comes from a same-day cache without a Ministry query: mfCached is true and mfRequestDateTime is the time of the oldest of those queries.

Parametersnipyrequired

sprawdz_regon

Look up entity data in the REGON register (Statistics Poland / GUS BIR) by NIP: REGON number, official name, legal form (legal or natural person), address (voivodeship, county, municipality). Covers ALL entities, including sole proprietors that are not in the KRS. For natural persons (GUS type F / LF) and civil partnerships (s.c.) only the NIP, name, entity type code (typ), form (forma: 'osoba fizyczna' / 'jednostka lokalna osoby fizycznej' / 'spółka cywilna'), town and activity status (status: active / ended) are returned — no REGON number, address, administrative units or dates (GDPR); the full entry is in the GUS REGON search (privacy.officialSource).

Parametersniprequired

sprawdz_vies

Validate a counterparty's EU VAT number in the VIES system (European Commission). For Polish (PL) numbers the address is reduced to the town, because the number may belong to a natural person (GDPR).

ParametersvatNumberrequiredcountryCoderequired

sprawdz_rachunek

Check whether a bank account number (NRB) appears in the VAT White List for a given NIP. Due diligence for payments above PLN 15,000.

ParametersniprequirednumerRachunkurequired

generuj_mikrorachunek

Generate the individual tax micro-account (for PIT/CIT/VAT payments) from a NIP. The server does not accept PESEL (personal ID) — for a PESEL compute it locally: BBAN = "101000712221" + PESEL + "0", IBAN = "PL" + ISO 7064 mod-97 check digits + BBAN (or use skanfirmy.pl/mikrorachunek, which computes it in the browser).

Parametersidentyfikatorrequired

szukaj_pkd

Search PKD 2025 business activity codes by activity name or code number.

Parameterszapytanierequired

oblicz_odsetki

Calculate statutory or commercial (B2B) late-payment interest, broken down by NBP reference-rate periods.

ParameterstyprequiredkwotarequireddataDorequireddataOdrequired

szukaj_katalog_api

Search otwarteAPI.pl, a catalog of public Polish and EU APIs (VAT, KRS, GUS, NBP, ECB, Eurostat and more). Returns matching entries with a link to each API's official docs. An empty query returns the whole catalog (optionally narrowed by scope or topic).

Parameterstematzasiegzapytanie

observe_nip

Add a NIP to monitoring. You get notified (via changes_since or email) when its VAT status, bank account, or registry data shown on the Ministry of Finance White List (name, address, KRS, REGON) changes. For natural persons running a business (entities without a KRS number) only the VAT status and masked bank accounts are monitored (GDPR): no name, address or REGON changes. Requires a skanfirmy API key (Authorization: Bearer, or the api_key argument). Free plan: up to 10 NIPs.

Parametersniprequiredapi_key

unobserve_nip

Stop watching a NIP — the watch is deleted right away. Requires a skanfirmy API key.

Parametersniprequiredapi_key

list_observations

Return the list of NIPs you monitor, with their current VAT status and last-checked date (name is null for natural persons running a business). Each entry keeps the raw Ministry of Finance literal in status_vat and, when a status is known, adds derived language-neutral fields vat_active (boolean) and status_vat_code (active/exempt/not_registered). Requires a skanfirmy API key.

Parametersapi_key

changes_since

Return changes (VAT status, bank accounts, or registry data — name, address, KRS, REGON — from the White List) detected since a given date for the NIPs you monitor. The field property is one of: status_vat, account_added, account_removed, name, address, krs, regon. For natural persons (entities without a KRS number; natural_person: true) only status_vat, account_added and account_removed are returned, account numbers are masked (check digits + last 4, e.g. 61…2874) and name is null (GDPR); check a specific account with sprawdz_rachunek. A polling channel for agents. Requires a skanfirmy API key.

Parameterssinceapi_key

set_webhook

Set (or clear) a push webhook URL for your monitoring, instead of or in addition to polling. When we detect a change for a monitored NIP, we send a POST signed with HMAC-SHA256 (X-Skanfirmy-Signature header). Returns the secret ONCE. Pass an empty url to disable. Requires a skanfirmy API key. Public https addresses only (port 443).

Parametersurlapi_key

Version history

3
  1. v1.4.0LatestOct 2, 2026
  2. v1.1.2Sep 18, 2026
  3. v1.1.1Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts