Skip to main content
Glama
CUF Health Portal MCP Server

CUF Health Portal MCP Server

CUF Health Portal MCP Server

An MCP (Model Context Protocol) server that exposes the CUF health portal as tools for Claude and other MCP clients.

Tools

Tool

Description

get_patient_info

Patient profile (name, contacts, NIF, SNS number)

list_appointments

Upcoming appointments

list_past_appointments

Full appointment history

list_clinical_documents

Imaging reports, lab reports, clinical files, etc.

get_clinical_document

Download a clinical document PDF by ID

list_exam_results

Active lab/exam results from the portal

list_invoices

All invoices

get_invoice

Download an invoice PDF by payment number

list_prescriptions

Exam prescriptions (scrapes www.cuf.pt)

get_prescription

Download a prescription PDF by download URL

Downloaded PDFs are saved to ./downloads/cuf/ by default (configurable via OUTPUT_DIR env var).

Related MCP server: jcs-mcp

Setup

Requirements

  • uv

  • A CUF portal account (saudecuf.pt)

Install

git clone <repo>
cd cuf-mcp
uv sync

Configure credentials

Create a .env file:

CUF_USERNAME=your.email@example.com
CUF_PASSWORD=yourpassword
OUTPUT_DIR=./downloads   # optional

Register with Claude Code

Add to ~/.claude/claude_desktop_config.json (or your MCP settings):

{
  "mcpServers": {
    "cuf-health": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/cuf-mcp", "python", "mcp_server.py"]
    }
  }
}

Then run /mcp in Claude Code to connect.

Run standalone (MCP Inspector)

uv run mcp dev mcp_server.py

Bulk download all records

uv run python download_cuf.py

Downloads all clinical documents and invoices to ./downloads/cuf/.

Architecture

Authentication

The portal uses two separate auth systems:

  • saudecuf.pt GraphQL API — JWT bearer token obtained via authenticationMutation. The JWT contains patientId, usercode, and internalPatientCode. Headers require x-channel-type-id: 1 and a per-request x-transaction-id UUID.

  • cuf.pt Drupal (prescriptions only) — Separate Drupal session cookie (SSESS*) obtained by POSTing to https://www.cuf.pt/mycuf/login. Prescriptions are server-rendered HTML, not available via GraphQL.

Key files

  • mcp_server.py — FastMCP server; defines all 10 tools; lazy-initializes a shared authenticated CufClient

  • cuf_client.py — Async CufClient class; wraps all GraphQL queries and the prescription scraper

  • download_cuf.py — Standalone bulk downloader script

WAF note

The portal runs behind a Barracuda WAF that blocks headless Chromium. Plain httpx with browser-like headers works fine.

Notes

  • list_exam_results currently returns an empty list — the getActiveExamResults GraphQL endpoint requires a separate auth scope not present in the standard JWT.

  • Prescriptions use internalPatientCode as the client identifier, not patientId.

  • Invoice paymentNumber format: "CCF2026/45291" → docSeries="CCF2026", docNumber="45291".

Available Tools

12 tools
get_clinical_documentA

Download a specific clinical document PDF by its ID.

Args: doc_id: The document ID from list_clinical_documents (e.g. "12345").

Returns the file path where the PDF was saved.

Inputs: doc_id (required). Returns: result

get_invoiceA

Download a specific invoice PDF by payment number.

Args: payment_number: The paymentNumber from list_invoices (e.g. "CCF2026/45291" or "FT FSDR2025/170390").

Returns the file path where the PDF was saved.

Inputs: payment_number (required). Returns: result

get_notificationsA

Get patient portal notifications.

Args: include_read: Whether to include already-read notifications (default: True).

Returns a list of dicts with keys: id, name, description, date, message, read, entityType, entityCode.

Inputs: include_read. Returns: result

get_patient_infoA

Get basic patient profile information (name, contacts, identity numbers).

Returns a dict with keys: fullName, title, contacts, identity.

Inputs: no named parameters.

get_prescriptionA

Download a prescription PDF by its download_url from list_prescriptions().

Args: download_url: The download_url field from list_prescriptions() output.

Returns the file path where the PDF was saved.

Inputs: download_url (required). Returns: result

list_appointmentsB

List upcoming and recent appointments.

Args: date_from: ISO date string (YYYY-MM-DD) to start from. Defaults to today.

Returns a list of dicts with keys: id, scheduledDatetime, medicalActName, staffName, siteName, status, type, canCancel, canReSchedule, and more.

Inputs: date_from. Returns: result

list_clinical_documentsA

List all clinical documents (imaging reports, cardiology, pathology, etc.).

Returns a list of dicts with keys: id, patientId, documentType, documentDate, fileName.

Inputs: no named parameters. Returns: result

list_exam_resultsA

List active lab/exam results available in the portal.

Returns a list of dicts with keys: code, report, client. Note: This section may be empty if no results are currently available.

Inputs: no named parameters. Returns: result

list_invoicesA

List all invoices from the CUF portal.

Returns a list of dicts with keys: id, code, paymentNumber, date, status, value, externalSiteCode.

Inputs: no named parameters. Returns: result

list_past_appointmentsA

List all past appointments (from 2000-01-01 to today).

Returns a list of dicts with keys: id, scheduledDatetime, medicalActName, staffName, siteName, status, type, and more.

Inputs: no named parameters. Returns: result

list_prescriptionsA

List exam prescriptions from the CUF portal (www.cuf.pt).

Scrapes the Drupal-rendered HTML page — prescriptions use a separate auth system from the GraphQL API. Returns list of dicts with: date, patient, site, download_url, document_id.

Args: years: List of years to fetch (default: current year and 2 prior years).

Inputs: years. Returns: result

parse_prescriptionA

Parse a downloaded prescription PDF with a local Ollama model.

Extracts text from the PDF and sends it to a local Ollama model for structured extraction. Falls back to vision-mode (image rendering) for image-based PDFs.

Args: file_path: Path to the prescription PDF (from get_prescription). model: Ollama model ID to use (default: "llama3.2"; use a vision model like "llava" if the PDF is image-based).

Returns structured dict with: patient, date, doctor, specialty, medications (list with name/dci/strength/form/quantity/posology/duration), prescription_number, notes.

Inputs: file_path (required), model.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools map cleanly to distinct resource/action pairs, and the list_/get_ pairing makes common document and invoice workflows obvious. However, list_appointments and list_past_appointments clearly overlap for recent past appointments, and list_exam_results vs list_clinical_documents have some potential boundary ambiguity around lab/pathology results. The descriptions help, but a couple of tools could still be confused.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: list_ for collections, get_ for individual items or PDF downloads, and parse_ for prescription extraction. This makes the tool set highly predictable and easy for an agent to navigate.

    Tool Count5/5

    12 tools is well-scoped for a health portal covering clinical documents, invoices, appointments, exam results, prescriptions, notifications, and patient info. Each tool has a clear purpose, and none feel redundant or superfluous.

    Completeness3/5

    Read-only retrieval is well covered: every listed resource has at least a list/get or download path, and prescription parsing adds useful post-processing. However, appointment fields like canCancel and canReSchedule indicate self-service actions that are not exposed, and there are no cancel/reschedule or update workflow tools. This creates notable dead ends for tasks beyond viewing or downloading.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Exposes the Joaquim Chaves Saúde patient portal as MCP tools, letting Claude or other clients fetch appointments, prescriptions, invoices, and documents from webapp.jcs.pt.
      11
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to read their own Clalit Health Services records—including lab results, prescriptions, lab orders, visit and hospital summaries, and source PDFs—through an AI assistant over MCP or a CLI, with local browser-based sign-in and session keep-alive.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to read a user's own lab results, imaging reports, visit summaries, and upcoming appointments from the beWell patient portal, with local sign-in and read-only access.
      6
      MIT