Skip to main content
Glama
bartosz-kuc

nfz-mcp

by bartosz-kuc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

honest-nfz-mcp

Local MCP server for the Polish National Health Fund (NFZ) public API — waiting lists ("kolejki") and the medical-service dictionary. No authentication required.

Part of the honest-mcp family of small, auditable, local-first MCP servers.

Why

Every Polish resident, at some point, wants to know "jak długo trzeba czekać na kardiologa?" — how long the queue for a cardiologist actually is. NFZ publishes this via a REST API but the friendly search on terminyleczenia.nfz.gov.pl doesn't help when you want to compare 20 providers at once or feed the data to an AI.

This server hands NFZ's data to your AI as structured JSON. Ask "cheapest wait time for a rehabilitation-cardiology facility in Mazowieckie?" and get an actual answer with provider names, wait statistics and — where NFZ provides them — first-available dates.

Related MCP server: korea-health-mcp-server

Features

Three tools:

  • search_queues — waiting list search: partial-name benefit + province + case (routine vs urgent) + optional locality (city/district), returns the first-available date (NFZ currently often leaves it empty) and the provider-reported wait statistics per provider.

  • search_benefits — search the NFZ service dictionary to discover the exact benefit name to use.

  • list_provinces — the 2-digit province code map (01–16).

Data source

  • Endpoint: api.nfz.gov.pl/app-itl-api/ — NFZ's public "Informator o Terminach Leczenia" API

  • No API key, no registration

  • Public info about NFZ-contracted providers only

Requirements

  • Python 3.10+

Setup

git clone https://github.com/bartosz-kuc/honest-nfz-mcp.git
cd honest-nfz-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

On Windows use python instead of python3, and venv\Scripts\pip / venv\Scripts\python instead of the venv/bin/... paths (here and in the configs below).

Register with Claude Code:

claude mcp add nfz /absolute/path/to/venv/bin/python /absolute/path/to/server.py

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "nfz": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Example usage

Note (September 2026): NFZ's API currently returns no dates for most queue entries, so first_available_date is often null. NFZ has also renamed many services (e.g. ŚWIADCZENIA Z ZAKRESU OKULISTYKI instead of PORADNIA OKULISTYCZNA) — use search_benefits to find the current wording.

"Which cardio-rehab facilities in Mazowieckie have the shortest wait?"

Two-step: search_benefits(name="kardio") → find exact benefit name → search_queues(benefit="ZAKŁAD/OŚRODEK REHABILITACJI KARDIOLOGICZNEJ", province="07", case=1, limit=25) → list of providers with their queue data.

"Any ophthalmology openings in Kraków?"

search_queues(benefit="ŚWIADCZENIA Z ZAKRESU OKULISTYKI", province="06", case=1, locality="KRAKÓW") — locality is a case-insensitive substring filter applied by the NFZ API, so it covers the whole province, not just the first result page. Matches are re-checked locally, scanning at most 10 result pages of 25.

Data flow

Your AI client
     ↕  MCP stdio
This server (Python, on your machine)
     ↕  HTTPS
api.nfz.gov.pl (National Health Fund)

No cloud middle. No telemetry.

Author

Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.

Consulting

Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.

License

MIT — see LICENSE.

Related

Available Tools

3 tools
list_provincesA

Return the mapping of 2-digit province codes to voivodeship names used by NFZ.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

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

With no annotations, the description must bear the full burden of behavioral disclosure. It states only the return content, not whether the operation is read-only, cached, or has any side effects. For a simple lookup this is a minor gap, but it does not disclose any extra behavioral traits beyond the bare return statement.

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?

A single, compact sentence that conveys the complete purpose without any fluff. All information is front-loaded and no sentence is wasted.

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?

For a static mapping retrieval with no parameters and no output schema, the description is entirely sufficient. An agent knows exactly what to expect and there are no hidden complexities that need explaining.

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 zero parameters, so according to the rubric the baseline is 4. There is nothing for the description to add about parameter meanings, and the description does not attempt to invent any.

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 action ('Return'), the resource ('mapping of 2-digit province codes to voivodeship names'), and the context ('used by NFZ'). It is instantly distinguishable from the sibling search tools, which are queries for benefits and queues, not static mappings.

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 that this tool is for retrieving a fixed reference mapping, which contrasts with the search functionality of the siblings. However, it does not explicitly state 'use when you need province codes' or explicitly name alternatives, though the context makes it obvious.

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

search_benefitsA

Search the NFZ benefit dictionary — the official service names that search_queues accepts. Use this to discover the exact wording before searching queues.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesPartial name to search for (case-insensitive)
limitNoMax results (default 25)

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explains that the tool searches a dictionary and that it returns official service names, which implies a read-only list operation. However, it does not disclose any side effects, permissions needed, pagination behavior, or what happens on no matches. While safe to assume, the description is thin on behavioral detail.

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, no filler. The first sentence defines the resource and purpose; the second provides usage context. Front-loaded with the key verb 'Search' and the specific resource. Every word 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?

The tool is simple (2 params, no output schema) and the description covers purpose and usage adequately. It implies the return value (a list of official names) but does not explicitly state the output format. Given the simplicity and the connection to `search_queues`, this is a minor gap, but the lack of an explicit return description slightly reduces completeness.

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

Parameters3/5

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

Schema coverage is 100% – both `name` and `limit` are fully described in the schema (partial name, case-insensitive, default 25). The description adds no extra meaning about parameters; it only talks about the overall purpose. Baseline of 3 is appropriate since structured data already documents parameters.

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 states the specific resource ('NFZ benefit dictionary') and that it provides official service names used by `search_queues`. This clearly distinguishes it from sibling tools like `search_queues` (which accepts these names) and `list_provinces` (which lists provinces, not benefits). The purpose is unambiguous.

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 gives explicit instruction: 'Use this to discover the exact wording before searching queues.' This tells the agent when to invoke the tool (before using `search_queues`) and the rationale. It implicitly contrasts with `search_queues` by positioning this as a prerequisite lookup step.

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

search_queuesA

Search NFZ waiting lists (kolejki) for a medical service in a province. Returns the first-available date and average wait time reported by each provider. benefit is a partial (case-insensitive) match on the official service name — use search_benefits first if unsure. case: 1 = stabilny (routine), 2 = pilny (urgent).

ParametersJSON Schema
NameRequiredDescriptionDefault
caseNo1 = stabilny (routine), 2 = pilny (urgent)
limitNoMax results to return (default 20, max 25 per NFZ API)
benefitYesPartial name of the medical service (e.g., 'PORADNIA KARDIOLOGICZNA')
localityNoOptional city filter (case-insensitive substring match on the response).
provinceYes2-digit province code (see list_provinces). E.g., 07 = MAZOWIECKIE.

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it delivers: it reveals the return payload (first-available date and average wait time per provider), the partial case-insensitive matching behavior of benefit, and the case semantics. It does not cover result ordering or no-results behavior, but the core behavioral traits an agent needs are disclosed upfront.

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?

Three sentences with the core purpose and payload front-loaded before parameter detail. The case explanation repeats schema-stated information, which is mild redundancy, but the prose remains compact and every sentence earns its place meaningfully.

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?

With no annotations and no output schema, the description compensates well by stating the return content (first-available date and avg wait time), matching behavior, and enum semantics. It could add result ordering or pagination notes for a provider-list search, which keeps it a notch below fully complete.

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 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains that benefit is a partial case-insensitive match against the official service name and routes uncertain agents to search_benefits. The case explanation duplicates the schema enum descriptions, but the partial-match clarification is no free value from the structured fields.

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?

States a specific action (search waiting lists) with a clear resource (NFZ kolejki), scope (by province) and outcome (returns first-available date and average wait time per provider). Differentiates cleanly from search_benefits (finds service names) and list_provinces (province codes), so an agent can tell them apart without opening schemas.

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?

Explicitly advises 'use search_benefits first if unsure' about the service name, which is direct routing guidance to a sibling. It defines the case enum values clearly. It does not state when to prefer list_provinces or explicitly exclude alternatives, but given the siblings are narrow utility lookups, the guidance is adequate.

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.

  1. 3 tool updatesv0.1.0
    • First observedlist_provinces
    • First observedsearch_benefits
    • First observedsearch_queues
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a distinct purpose: discovering official benefit names, mapping province codes, and querying waiting lists. No functional overlap exists between them, and their descriptions explicitly reference how they fit together, eliminating ambiguity.

Naming Consistency5/5

All tools follow a clear verb_noun pattern with snake_case: search_benefits, list_provinces, search_queues. The naming is uniform and predictable, with verbs indicating the action and nouns indicating the resource.

Tool Count5/5

The server is tightly scoped to NFZ waiting list queries. Three tools cover the essential steps (lookup benefit names, get province codes, search queues) without redundant or extraneous tools, making the count ideal for the domain.

Completeness5/5

The tools form a complete workflow: search_benefits ensures valid query terms, list_provinces provides required codes, and search_queues delivers the core function. There are no obvious gaps for the stated purpose, as all necessary prerequisites are handled.

Resources

Related MCP Connectors

Related MCP Servers

  • atlas-przetargow-mcp-py

    dam2452
    F
    license
    A
    quality
    C
    maintenance
    Enables searching and analyzing Polish public procurement tenders from BZP and TED, including filtering, tender details and timelines, offers and contract values, buyer/contractor profiles, CPV code lookup, and regional statistics, with optional AI-summary endpoints.
    12
    1
    -