Skip to main content
Glama

regon-mcp

A Model Context Protocol server that gives AI assistants clean, typed access to the Polish REGON business register (GUS BIR1). Look up any Polish company by NIP, REGON, or KRS and get back structured data — name, address, legal form, activity codes — without touching the underlying SOAP API.

The official GUS BIR1 API is a WCF SOAP service with WS-Addressing, MTOM multipart responses, an HTTP-header session token, and XML-nested-inside-XML result payloads. regon-mcp hides all of that behind a handful of simple tools.

Built and maintained by Smart Mobile House — secure AI implementation for enterprise.

Background and design notes: the regon-mcp write-up.

Tools

Tool

Description

search_by_nip(nip)

Look up an entity by 10-digit NIP (tax id).

search_by_regon(regon)

Look up an entity by 9- or 14-digit REGON.

search_by_krs(krs)

Look up an entity by 10-digit KRS (court register).

search_bulk(identifiers, id_type)

Look up up to 20 entities of one type at once.

get_full_report(regon, report_type)

Fetch a detailed report for one entity.

list_report_types()

List valid report names, with guidance on which to use.

Every response includes a source block that names the register (REGON / GUS), the environment, and a UTC retrieved_at timestamp — so downstream use can cite the data correctly, as GUS requires.

Related MCP server: nipregon-mcp

Quick start

No install needed — run it straight from the repo with uv:

uvx --from git+https://github.com/SmartMobileHouse/regon-mcp regon-mcp

By default it uses the public test key against the anonymized GUS test database, so it runs with zero setup. For live data, request a free USER_KEY from regon_bir@stat.gov.pl and set the environment variables below.

Use it in Claude Desktop / Claude Code

Add to your MCP config (e.g. claude_desktop_config.json or a project .mcp.json):

{
  "mcpServers": {
    "regon": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SmartMobileHouse/regon-mcp", "regon-mcp"],
      "env": {
        "REGON_API_KEY": "your-user-key",
        "REGON_ENV": "prod"
      }
    }
  }
}

During development, point it at a local checkout instead:

{
  "mcpServers": {
    "regon": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/regon-mcp", "regon-mcp"],
      "env": { "REGON_API_KEY": "abcde12345abcde12345" }
    }
  }
}

Configuration

Variable

Default

Description

REGON_API_KEY

public test key

Your GUS BIR USER_KEY.

REGON_ENV

test

test (anonymized data) or prod (live data).

REGON_TIMEOUT

30

HTTP timeout in seconds.

Use REGON_ENV=prod only with a real USER_KEY; the test key works only against the test environment.

Development

git clone https://github.com/SmartMobileHouse/regon-mcp
cd regon-mcp
uv sync                 # create the venv and install deps
uv run pytest           # offline tests: validation, parsing, mocked client,
                        # and an in-memory MCP tool-discovery smoke test.
                        # (network tests are deselected by default)
uv run regon-mcp        # run the server over stdio

# Live tests against the GUS endpoint (deselected unless opted in):
REGON_RUN_NETWORK=1 uv run pytest -m network            # session lifecycle (test env)
REGON_PROD_KEY=<your-key> uv run pytest -m network      # positive-control on live data

The client is a small hand-rolled SOAP layer over httpx (see src/regon_mcp/client.py) — no heavyweight SOAP stack, no runtime WSDL fetch.

Notes & limitations

  • The GUS test database is anonymized and returns little or no entity data. Meaningful results require a production USER_KEY with REGON_ENV=prod.

  • Respect the GUS terms of use and rate limits. This project is an independent open-source client and is not affiliated with or endorsed by GUS.

  • Data belongs to GUS. When you present it, cite REGON / GUS with the retrieval date (surfaced in every response's source block).

License

MIT © Smart Mobile House

Available Tools

6 tools
get_full_reportA

Fetch a detailed REGON report for one entity by REGON.

Choose report_type from list_report_types(), based on the entity's `type`
and `silo_id` returned by a search.

Inputs: regon (required), report_type (required).

list_report_typesA

List valid report_type values for get_full_report(), with guidance.

These are the BIR1.1 report names. Picking the right report:
  - type "P" (legal person)   -> BIR11OsPrawna
  - type "F" (natural person) -> by silo_id:
      1 -> BIR11OsFizycznaDzialalnoscCeidg
      2 -> BIR11OsFizycznaDzialalnoscRolnicza
      3 -> BIR11OsFizycznaDzialalnoscPozostala
      4 -> BIR11OsFizycznaDzialalnoscSkreslonaDo20141108
  - local units (LP / LF) -> BIR11JednLokalnaOsPrawnej / ...OsFizycznej

Inputs: no named parameters.

search_bulkA

Look up up to 20 entities of the same identifier type in one call.

id_type must be one of: "nip", "krs", "regon9", "regon14".

The response adds `requested` (normalized inputs) and `unmatched` (requested
ids with no returned row) so partial results are explicit. For KRS the
service does not echo the KRS in search rows, so `unmatched` is null there.

Inputs: id_type (required), identifiers (required).

search_by_krsA

Look up a Polish business entity by KRS (10-digit court-register number).

Inputs: krs (required).

search_by_nipA

Look up a Polish business entity by NIP (10-digit tax id).

Returns basic registry data (name, REGON, address, entity type). Use the
returned REGON with get_full_report() for the detailed record.

Inputs: nip (required).

search_by_regonA

Look up a Polish business entity by REGON (9- or 14-digit statistical id).

Inputs: regon (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct, well-defined purpose: three searches by specific identifiers (REGON, NIP, KRS), a bulk search, a detailed report fetcher, and a report type lister. There is no overlap or ambiguity between tools.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case: search_by_regon, search_by_nip, search_by_krs, search_bulk, get_full_report, list_report_types. The naming is predictable and uniform.

    Tool Count5/5

    Six tools is well-scoped for a registry lookup service. Each tool is necessary and covers a core function without unnecessary extras or missing essential operations.

    Completeness5/5

    The tool set fully covers the domain of Polish business registry lookups: searching by all major identifiers, bulk lookup, and obtaining detailed reports. The list_report_types tool ensures users can correctly choose report types, and the flow from search to report is well-supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides access to Poland's largest business registry database, enabling company search, beneficiary checks, and financial document retrieval via natural language.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Look up Polish companies from any AI assistant: registry data (KRS, REGON, CEIDG), VAT white list checks before payments, and financial statements of 4.4M businesses. Read-only tools backed by official public registers.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables looking up Polish companies by NIP, REGON, or KRS number to retrieve their registered name, legal address, and entity type from Statistics Poland's official register.
      78 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides AI assistants access to Polish public registers, enabling company lookups in KRS, VAT whitelist and bank-account checks, KRS extract retrieval, and offline validation of NIP, REGON, KRS, NRB, and KW numbers.
      MIT