bartmichalak/nfz-mcp-server

NFZ Appointment Search MCP Server

This MCP (Model Context Protocol) server provides tools for searching available NFZ (National Health Fund) appointments and healthcare services in Poland. It interfaces with the official NFZ API to provide real-time information about available medical appointments, healthcare providers, and medical benefits.

Features

• Appointment Search: Search for available NFZ appointments by various criteria
• Healthcare Provider Search: Find healthcare providers and facilities
• Medical Benefits Search: Search for available medical procedures and services
• Location-based Search: Search by province, city, and street
• Urgent vs Stable Cases: Support for both urgent and stable medical cases
• Alternative Locations: Find alternative locations for specific appointments
• API Information: Get information about the NFZ API status

Installation

1. Clone this repository:

git clone <repository-url>
cd mcp-server-demo

2. Install dependencies:

pip install -e .

Usage

Install server

You can install this server in CLaude Desktop and interact with it right away by running:

uv run mcp install main.py

Please remember to restart Claude Desktop after running the above command.

Available Tools

1. Search Appointments (search_appointments)

Search for available NFZ appointments with various filters.

Parameters:

• case (optional): Case type (1=stable, 2=urgent)
• province (optional): Province code (e.g., "07" for Mazowieckie)
• benefit (optional): Medical benefit/service name
• locality (optional): City/locality name
• provider (optional): Healthcare provider name
• page (default: 1): Page number for pagination
• limit (default: 10, max: 25): Results per page

Example:

# Search for cardiology appointments in Warsaw
search_appointments(
    case=1,
    province="07",
    benefit="kardiologia",
    locality="Warszawa"
)

2. Get Appointment Details (get_appointment_details)

Get detailed information about a specific appointment.

Parameters:

• appointment_id: The ID of the appointment

3. Get Alternative Locations (get_alternative_locations)

Find alternative locations for a specific appointment.

Parameters:

• appointment_id: The ID of the appointment

4. Search Benefits (search_benefits)

Search for available medical benefits/procedures.

Parameters:

• name (optional): Name or part of the benefit name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

Example:

# Search for cardiology benefits
search_benefits(name="kardiologia")

5. Search Providers (search_providers)

Search for healthcare providers.

Parameters:

• name (optional): Name or part of the provider name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

6. Search Localities (search_localities)

Search for cities/localities.

Parameters:

• name (optional): Name or part of the locality name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

7. Search Places (search_places)

Search for healthcare places/locations.

Parameters:

• name (optional): Name or part of the place name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

8. Search Streets (search_streets)

Search for streets.

Parameters:

• name (optional): Name or part of the street name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

9. Get API Info (get_api_info)

Get information about the NFZ API version and status.

10. Search Appointments by Specialty (search_appointments_by_specialty)

Convenience function to search for appointments by medical specialty.

Parameters:

• specialty: Medical specialty (e.g., "kardiologia", "ortopedia")
• province (optional): Province code
• locality (optional): City/locality name
• case (default: 1): Case type (1=stable, 2=urgent)
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

11. Get Urgent Appointments (get_urgent_appointments)

Search specifically for urgent appointments (case=2).

Parameters:

• province (optional): Province code
• locality (optional): City/locality name
• benefit (optional): Medical benefit/service name
• page (default: 1): Page number
• limit (default: 10, max: 25): Results per page

Available Resources

1. Appointment Details (nfz://appointment/{appointment_id})

Get detailed information about a specific NFZ appointment.

2. Benefit Information (nfz://benefit/{benefit_name})

Get information about a specific medical benefit.

Province Codes

Common province codes for Poland:

• 01 – dolnośląskie
• 02 – kujawsko-pomorskie
• 03 – lubelskie
• 04 – lubuskie
• 05 - łódzkie
• 06 – małopolskie
• 07 – mazowieckie
• 08 – opolskie
• 09 – podkarpackie
• 10 – podlaskie
• 11 – pomorskie
• 12 – śląskie
• 13 – świętokrzyskie
• 14 – warmińsko-mazurskie
• 15 – wielkopolskie
• 16 – zachodniopomorskie

API Response Format

The server returns data in JSON format following the NFZ API structure:

{
  "meta": {
    "@context": "/schema/queue",
    "count": 4088,
    "page": 1,
    "limit": 10
  },
  "links": {
    "first": "/queues?page=1&limit=10&case=1&province=07&benefit=poradnia",
    "prev": null,
    "self": "/queues?page=1&limit=10&case=1&province=07&benefit=poradnia",
    "next": "/queues?page=2&limit=10&case=1&province=07&benefit=poradnia",
    "last": "/queues?page=409&limit=10&case=1&province=07&benefit=poradnia"
  },
  "data": [
    // Appointment data here
  ]
}

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues
• API rate limiting
• Invalid parameters
• Server errors

All errors are returned in a structured format with descriptive messages.

Dependencies

• mcp[cli]>=1.10.0 - MCP server framework
• requests>=2.31.0 - HTTP client for API calls

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on the GitHub repository.