How do I use regon-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@regon-mcp Look up company by NIP 1234567890" 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.

regon-mcp

by SmartMobileHouse

Overview Schema Related Servers Score Discussions

Python

Remote

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.

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: KRS Poland MCP Server

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.

ParametersJSON Schema

Name	Required	Description	Default
`regon`	Yes
`report_type`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It adds useful context that report_type depends on entity type and silo_id, and clarifies it's a single-entity fetch. However, it does not disclose response format, error behavior, or any potential side effects, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the core purpose and followed by essential usage guidance. No filler, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no output schema, the description covers the necessary invocation steps and prerequisite dependencies. It omits explicit return format or error cases, but the name and 'detailed report' convey the basic output expectation adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates by explaining that regon is the entity identifier and report_type should be selected from list_report_types(). This gives meaningful meaning to both parameters beyond their bare string types, though it doesn't specify exact formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Fetch a detailed REGON report for one entity by REGON.' This clearly differentiates it from sibling search tools and list_report_types, and states exactly what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the user to choose report_type from list_report_types() based on the entity's type and silo_id returned by a search, establishing a clear usage workflow. It doesn't explicitly state when not to use it, but the prerequisite and selection guidance are strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the tool lists valid values, identifies these as 'BIR1.1 report names', and explains the mapping logic. While it doesn't mention side effects or return format, the operation is inherently read-only and the description adds meaningful context about the semantic relationships between types and reports.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat verbose but each sentence and line earns its place. It front-loads the purpose ('List valid report_type values') and then provides structured guidance in a readable mapping format. The length is appropriate given the complexity of the type-to-report mapping, and there is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple in function but complex in the mapping it documents. The description fully covers the report type selection logic, including all relevant type indicators and silo_id branches. There is no output schema, but the description explains the essential semantics and the relationship to get_full_report(), making it complete for an agent to invoke or understand the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters and the schema description coverage is 100%, so the baseline is 4. The description adds no parameter-specific information because there are no parameters to describe. It does discuss the output values, which is beyond parameter semantics but still useful. Since there is no schema to clarify, the description fully compensates by explaining the meaning of the report types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List valid report_type values for get_full_report()'. It uses a specific verb ('List') and a specific resource ('report_type values for get_full_report()'), and it distinguishes itself from sibling search tools by focusing on report type enumeration rather than entity lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each report type through the 'Picking the right report' section, including a breakdown by type ('P' vs 'F') and silo_id. This is not just context; it gives decision criteria and references the companion tool get_full_report(), making it clear where this tool fits in the workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`id_type`	Yes
`identifiers`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses response fields (`requested` and `unmatched`) that clarify partial result behavior, and it highlights a KRS-specific quirk where `unmatched` is null. It also mentions the 20-entity limit. This adds meaningful behavioral context beyond a simple search tool, though it does not cover error handling or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the main purpose. Each sentence adds value: the limit/type constraint, the allowed id_type values, and the response field explanation. There is no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description covers the core functionality, limits, and response fields, including an important edge case (KRS unmatched behavior). It is complete enough for an agent to select and invoke the tool correctly, though it omits details like error handling or full response schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explicitly lists allowed id_type values and states the same-identifier-type requirement. It also implies identifiers is a list of IDs (via 'requested ids') and caps it at 20. This provides essential semantics not in the schema, though it doesn't detail identifier format or normalization rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Look up up to 20 entities of the same identifier type in one call.' It uses a specific verb ('look up'), identifies the resource ('entities'), and distinguishes itself from sibling single-entity tools by emphasizing the bulk nature and identifier-type constraint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for batching multiple lookups of the same identifier type, contrasting with sibling single-entity search tools. It also explicitly restricts id_type to specific values. However, it does not explicitly say 'use this instead of multiple search_by_* calls' or state when not to use it, so it lacks explicit alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_by_krsA

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

ParametersJSON Schema

Name	Required	Description	Default
`krs`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only says 'look up' without disclosing potential errors, authentication requirements, or whether the result includes the full entity data or just confirmation of existence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence that is front-loaded with the action and resource, no redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter lookup, the description is mostly sufficient, but it lacks a description of the return value or behavior for invalid KRS numbers, and the absence of an output schema leaves the agent to guess what 'look up' returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines 'krs' as a string, but the description adds critical format detail ('10-digit court-register number'), which compensates for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Look up a Polish business entity by KRS (10-digit court-register number)', which clearly identifies the resource (Polish business entity), the specific identifier (KRS), and the unique scope (court-register number), distinguishing it from siblings that search by REGON/NIP.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a KRS is available but does not explicitly discuss alternatives like search_by_regon or search_by_nip, nor when to prefer search_bulk.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`nip`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description carries full burden; it discloses return fields (name, REGON, address, entity type) and relationship to get_full_report. Does not mention error handling or input formatting edge cases, but for a simple lookup this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded action and clear structure: first sentence states what is looked up and input format, second states output and suggested next step. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description lists returned fields and points to get_full_report for richer data. With only one parameter and clear purpose, it is adequate, though it omits not-found behavior or NIP formatting variations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has no description for the single nip parameter (0% coverage); description adds essential meaning by specifying it is a 10-digit tax id and clarifies how the returned REGON is used. This meaningfully compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Look up' and identifies resource 'Polish business entity by NIP', explicitly distinguishing from sibling search_by_regon/search_by_krs by identifier and from get_full_report by noting basic vs. detailed data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context: use when you have a NIP and need basic registry data, with explicit follow-up to get_full_report for the detailed record. Does not explicitly rule out sibling search tools, but the identifier-specific scope is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_by_regonA

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

ParametersJSON Schema

Name	Required	Description	Default
`regon`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the lookup purpose and does not disclose whether it is read-only, what the response looks like, or any constraints or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise, direct, and free of unnecessary detail. Every word adds value, focusing on the essential purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter lookup tool, the description covers the core purpose but lacks information about the return format, error handling, or any usage context. With no output schema, the description should at least hint at what the tool returns upon success.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only declares a string property 'regon' with no description. The description compensates by explaining that REGON is a 9- or 14-digit statistical id, which clarifies the expected format and meaning for the single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('look up'), the resource ('Polish business entity'), and the specific identifier ('REGON'). It effectively distinguishes this from siblings like search_by_nip and search_by_krs by focusing on the REGON id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for when you have a REGON, but it doesn't explicitly state when to prefer this over alternatives or mention any exclusions. No guidance on context or when-not-to-use is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.2.1Aug 10, 2026
- First observedget_full_report
- First observedlist_report_types
- First observedsearch_bulk
- First observedsearch_by_krs
- First observedsearch_by_nip
- First observedsearch_by_regon

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

nipregon A
pl.nipregon
Polish company registry: 4.4M firms, KRS/REGON data, VAT white list checks, financial statements
Government Data Open Data
72
skanfirmy.pl A
io.github.bartosz-kuc
Verify Polish companies by NIP/KRS/REGON + EU VAT (VIES). 9 MCP tools, no key.
Government Data Legal & Compliance
141
pohjola-api A
io.github.nousulabs-debug
Agent-native API for Finnish public company data via YTJ. Pay-per-call $0.01 USDC over x402.
Government Data Open Data
12
Sirenic A
eu.sirenic
French & European company registry for AI agents: KYB, sanctions, annual accounts. x402, no API key.
Government Data Open Data
772

Related MCP Servers

Rejestr.io MCP Server
Government Data Open Data
KolegaLiterat
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.
Updated 8 months ago (2026-01-05 09:52 UTC)
1
-
KRS Poland MCP Server
Government Data Open Data
pkolawa
A
license
C
quality
D
maintenance
Enables querying the Polish National Court Register (KRS) to retrieve current and historical entity data.
Updated 14 days ago (2026-08-23 10:28 UTC)
2
321
4
MIT
nipregon-mcp
Government Data Finance
AMR-DEV-PS
A
license
A
quality
B
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.
Updated 2 months ago (2026-06-23 08:27 UTC)
4
MIT
Polish Business Intelligence
Government Data Finance Open Data
neflingcreations
A
license
A
quality
B
maintenance
Provides AI agents with real-time access to Polish official data: VAT whitelist for company verification and NBP exchange rates, enabling checks on VAT status, company details, and currency conversion without API keys.
Updated 2 months ago (2026-07-05 09:22 UTC)
5
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SmartMobileHouse/regon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server