{
  "markdown": "# regon-mcp\n\n<!-- mcp-name: io.github.SmartMobileHouse/regon-mcp -->\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI\nassistants clean, typed access to the **Polish REGON business register** (GUS\nBIR1). Look up any Polish company by **NIP**, **REGON**, or **KRS** and get back\nstructured data — name, address, legal form, activity codes — without touching\nthe underlying SOAP API.\n\nThe official [GUS BIR1 API](https://api.stat.gov.pl/Home/RegonApi) is a WCF SOAP\nservice with WS-Addressing, MTOM multipart responses, an HTTP-header session\ntoken, and XML-nested-inside-XML result payloads. `regon-mcp` hides all of that\nbehind a handful of simple tools.\n\n> Built and maintained by [Smart Mobile House](https://smartmobilehouse.com) —\n> secure AI implementation for enterprise.\n\n## Tools\n\n| Tool | Description |\n| --- | --- |\n| `search_by_nip(nip)` | Look up an entity by 10-digit NIP (tax id). |\n| `search_by_regon(regon)` | Look up an entity by 9- or 14-digit REGON. |\n| `search_by_krs(krs)` | Look up an entity by 10-digit KRS (court register). |\n| `search_bulk(identifiers, id_type)` | Look up up to 20 entities of one type at once. |\n| `get_full_report(regon, report_type)` | Fetch a detailed report for one entity. |\n| `list_report_types()` | List valid report names, with guidance on which to use. |\n\nEvery response includes a `source` block that names the register (REGON / GUS),\nthe environment, and a UTC `retrieved_at` timestamp — so downstream use can cite\nthe data correctly, as GUS requires.\n\n## Quick start\n\nNo install needed — run it straight from the repo with\n[uv](https://docs.astral.sh/uv/):\n\n```bash\nuvx --from git+https://github.com/SmartMobileHouse/regon-mcp regon-mcp\n```\n\nBy default it uses the **public test key** against the anonymized GUS test\ndatabase, so it runs with zero setup. For live data, request a free `USER_KEY`\nfrom `regon_bir@stat.gov.pl` and set the environment variables below.\n\n### Use it in Claude Desktop / Claude Code\n\nAdd to your MCP config (e.g. `claude_desktop_config.json` or a project\n`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"regon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/SmartMobileHouse/regon-mcp\", \"regon-mcp\"],\n      \"env\": {\n        \"REGON_API_KEY\": \"your-user-key\",\n        \"REGON_ENV\": \"prod\"\n      }\n    }\n  }\n}\n```\n\nDuring development, point it at a local checkout instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"regon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"/absolute/path/to/regon-mcp\", \"regon-mcp\"],\n      \"env\": { \"REGON_API_KEY\": \"abcde12345abcde12345\" }\n    }\n  }\n}\n```\n\n## Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `REGON_API_KEY` | public test key | Your GUS BIR `USER_KEY`. |\n| `REGON_ENV` | `test` | `test` (anonymized data) or `prod` (live data). |\n| `REGON_TIMEOUT` | `30` | HTTP timeout in seconds. |\n\nUse `REGON_ENV=prod` only with a real `USER_KEY`; the test key works only\nagainst the test environment.\n\n## Development\n\n```bash\ngit clone https://github.com/SmartMobileHouse/regon-mcp\ncd regon-mcp\nuv sync                 # create the venv and install deps\nuv run pytest           # offline tests: validation, parsing, mocked client,\n                        # and an in-memory MCP tool-discovery smoke test.\n                        # (network tests are deselected by default)\nuv run regon-mcp        # run the server over stdio\n\n# Live tests against the GUS endpoint (deselected unless opted in):\nREGON_RUN_NETWORK=1 uv run pytest -m network            # session lifecycle (test env)\nREGON_PROD_KEY=<your-key> uv run pytest -m network      # positive-control on live data\n```\n\nThe client is a small hand-rolled SOAP layer over `httpx` (see\n`src/regon_mcp/client.py`) — no heavyweight SOAP stack, no runtime WSDL fetch.\n\n## Notes & limitations\n\n- The **GUS test database is anonymized** and returns little or no entity data.\n  Meaningful results require a production `USER_KEY` with `REGON_ENV=prod`.\n- Respect the GUS terms of use and rate limits. This project is an independent\n  open-source client and is not affiliated with or endorsed by GUS.\n- Data belongs to GUS. When you present it, cite **REGON / GUS** with the\n  retrieval date (surfaced in every response's `source` block).\n\n## License\n\n[MIT](LICENSE) © Smart Mobile House\n",
  "bytes": 4327,
  "sha": "757089c0c5b4d46cfefea6cbd7daf8d4e8d65b2278d0709e544913a0042dc96d",
  "repo_slug": "smartmobilehouse/regon-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_smartmobilehouse_regon_mcp_4905149a/readme"
}