Skip to main content
Glama

jcs-mcp

An MCP server that exposes the Joaquim Chaves Saúde (JCS) patient portal (webapp.jcs.pt) as tools for Claude and other MCP clients.

It lets you ask Claude things like:

  • "Show me my upcoming appointments"

  • "What prescriptions do I have active?"

  • "Download my latest exam result and summarise it"

  • "List my invoices from the past 6 months"

Features

11 MCP tools covering the full JCS portal:

Tool

Description

jcs_login(password)

Authenticate; session saved to ~/.jcs_session.json (auto-renewed)

get_patient_info()

Name, email, patient ID

list_timeline(rows_to_skip?, archived?)

Main health feed — exam results, appointment confirmations, documents

list_notifications(rows_to_skip?, archived?)

Notifications and messages

get_message(id)

Full message detail; body contains signed document URIs

list_appointments()

Upcoming and recent appointments from the calendar

list_prescriptions(include_expired?)

Active (and optionally expired) prescriptions

list_invoices()

Invoices (Faturas/Recibos) from the patient profile

get_document_content(uri)

Fetch HTML exam result content from a signed URI

download_document(uri, filename?)

Download a PDF document, saved to ./downloads/jcs/documentos/

parse_prescription(file_path, model?)

Parse a prescription PDF with a local Ollama model

Session management

Authentication uses OAuth2 Resource Owner Password Grant against the GatewayBox platform. After the first jcs_login() call the session is persisted to ~/.jcs_session.json and reloaded automatically on subsequent calls. If JCS_PASSWORD is set in .env, the server will auto-login when the session expires — no manual intervention needed.

Prescription parsing

parse_prescription extracts structured data from a downloaded prescription PDF using a local Ollama model:

{
  "patient": "...",
  "date": "YYYY-MM-DD",
  "doctor": "...",
  "specialty": "...",
  "medications": [
    {
      "name": "...", "dci": "...", "strength": "...",
      "form": "...", "quantity": "...", "posology": "...", "duration": "..."
    }
  ],
  "prescription_number": "...",
  "notes": "..."
}

For image-based PDFs it falls back to vision mode automatically (use a vision-capable model like llava).

Related MCP server: CUF Health Portal MCP Server

Requirements

  • Python 3.10+

  • uv

  • A JCS account at webapp.jcs.pt

  • Your device UUID and device token key (see Auth setup below)

  • Ollama (optional, only needed for parse_prescription)

Installation

git clone https://github.com/nathanfolkman/jcs-mcp.git
cd jcs-mcp
uv sync

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env
# Required
JCS_PHONE_NUMBER=+351912345678

# Optional — if set, the server will auto-login when the session expires
JCS_PASSWORD=your_password

# Required for first login (see Auth setup below)
JCS_DEVICE_UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
JCS_DEVICE_DTK=your_device_token_key

# Optional — where to save downloaded documents (default: ./downloads)
OUTPUT_DIR=./downloads

Auth setup

The JCS API uses a GatewayBox device registration system. Your script must present a device UUID and device token key (dtk) that are already registered with the server — unrecognised devices are rejected.

The easiest way to obtain these is from your browser session on webapp.jcs.pt:

  1. Open Chrome DevTools → Application → Local Storage → https://webapp.jcs.pt

  2. Find the key that contains your appUuid — this is your JCS_DEVICE_UUID

  3. Open DevTools → Network, log in normally, and look for the POST /api/device/token response — the deviceToken field is your JCS_DEVICE_DTK

Set both values in .env. After the first successful jcs_login() call they are also persisted to ~/.jcs_session.json.

Usage

With Claude Code

Add to your MCP settings (e.g. ~/.claude.json):

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

MCP Inspector (development)

uv run mcp dev mcp_server.py

Standalone

uv run python mcp_server.py

First-time login

If JCS_PASSWORD is not set in .env, call the login tool explicitly once:

jcs_login(password="your_password")

The session is saved and reused automatically until it expires (~24 hours).

Project structure

jcs-mcp/
├── jcs_client.py     # Async HTTP client (GatewayBox OAuth2 + all API methods)
├── mcp_server.py     # FastMCP server — 11 tools
├── pyproject.toml    # Dependencies
└── .env              # Credentials (not committed)

API notes

The JCS webapp is a single-page application built on the GatewayBox platform by Seamlink. All API endpoints were reverse-engineered from network traffic. Key facts:

  • Base URL: https://webapp.jcs.pt

  • Auth: OAuth2 password grant via POST /Token with uid, AppUuid, and dtk custom headers

  • All data endpoints use POST with a JSON body containing device (the appUuid)

  • Document URIs are signed, time-limited tokens embedded in message body HTML as data-attach-html attributes

  • HTML exam results: GET /api/attachdata/getcontent?uri=...

  • PDF documents: GET /api/attachdata/getfile?uri=...

License

MIT

Available Tools

11 tools
download_documentA

Download a clinical document PDF by signed URI. Saves to downloads/jcs/documentos/.

The uri comes from get_message() response.

Args: uri: Signed document URI from a message detail response. filename: Optional filename (e.g. "resultado_patologia.pdf").

Returns: Absolute path to the saved PDF file.

Inputs: uri (required), filename. Returns: result

get_document_contentA

Fetch the HTML content of a clinical document or exam result.

The uri comes from get_message() response (in events[] or external_ref). Returns: {FileName, contentType, html}

Args: uri: Signed document URI from a message detail response.

Inputs: uri (required).

get_messageA

Get full detail for a message/notification by ID.

The response includes the subject, body, linked events (appointments), and attachment URIs. Use get_document_content(uri) or download_document(uri) with any uri values found in the response to access the actual documents.

Args: message_id: Numeric message ID (from list_timeline or list_notifications).

Inputs: message_id (required).

get_patient_infoB

Return patient profile: Name, Email, patientId, accounts.

Inputs: no named parameters.

jcs_loginA

Log in to JCS with phone number (from env) + password.

Only needs to be called once — the session is saved to ~/.jcs_session.json and reused automatically until it expires (~24h).

Returns: {"success": True, "patient_name": "...", "patient_id": "..."}

Inputs: password (required).

list_appointmentsA

Return upcoming and recent appointments from the calendar.

Each event has: date, time, description, location (clinic), patient name.

Inputs: no named parameters.

list_invoicesA

Return invoices (Faturas) from the patient profile.

Each item contains clinic, invoice number (Fatura/Recibo), date, amount. Use download_document(uri) with the item's attach URI to download the PDF.

Inputs: no named parameters.

list_notificationsA

Return notifications/messages list. Returns {items, channels}.

Args: rows_to_skip: Pagination offset (default 0). archived: Include archived notifications (default False).

Inputs: archived, rows_to_skip.

list_prescriptionsB

Return prescriptions list.

Args: include_expired: Include expired prescriptions (default False).

Inputs: include_expired.

list_timelineA

Return the main health feed — exam results, appointment confirmations, docs, etc.

Items have: id, subject, body_preview, msgtype, publish_date, un_read, events[]. Use get_message(id) to fetch full detail + attachment URIs for a specific item.

Args: rows_to_skip: Pagination offset (default 0). archived: Include archived items (default False).

Inputs: archived, rows_to_skip.

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 download_document). 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.8/5.0

    Scored across 11 tools

    Disambiguation3/5

    Most tools are clearly distinct, but list_timeline and list_notifications overlap significantly—both return lists of messages with similar arguments and point to get_message for details. Additionally, get_document_content and download_document both handle attachment URIs, which could cause misselection without careful reading.

    Naming Consistency4/5

    The naming pattern is predominantly verb_noun (get_patient_info, list_appointments, download_document, parse_prescription), which is consistent and predictable. The outlier is jcs_login, which breaks the pattern by using a product prefix and lacking a clear object, introducing minor inconsistency.

    Tool Count5/5

    With 11 tools, the server is well-scoped for a healthcare portal client. It covers authentication, data retrieval, document access, and a niche parsing feature without being bloated or too thin. Each tool serves a distinct purpose in the overall workflow.

    Completeness4/5

    The tool surface provides a complete read-only lifecycle for the domain: listing and getting messages, appointments, prescriptions, invoices, and documents. Minor gaps exist, such as no ability to search, mark-as-read, or perform actions like scheduling appointments, but these are not core to the apparent purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    • JusPronto is case-management software for Brazilian law firms. Its remote MCP server (OAuth 2.1 with PKCE, per-permission scopes, audit log) lets Claude and ChatGPT read the firm's own cases, deadlines, agenda, recent court movements and case files with the page cited. Write actions require the lawyer's approval. Requires a JusPronto account.

    • Jane App MCP server for ChatGPT, Claude and any AI agent: list appointments, read the Wait List, book a Wait List client, email an intake form, read accounts receivable, send a Pay Balance email, list unscheduled patients and add a return visit reminder in your own Jane App account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Jane App yourself; Cotlet does not store your password and you need no Jane App API key. About the official Jane App API: Jane has an API, but only for approved Technology Partners (checked 27 Oct 2026). Jane says it is not launching an open, public API and that clinics cannot build their own integrations. Setup and FAQ: https://cotlet.dev/integrations/jane-app-api-mcp-server

    • SimplePractice MCP server for ChatGPT, Claude and any AI agent: list appointments, accept appointment request, share intake documents, list outstanding balances, list claims, set appointment status and send secure message in your own SimplePractice account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to SimplePractice yourself; Cotlet does not store your password and you need no SimplePractice API key. About the official SimplePractice API: SimplePractice has no public API for practices (checked 27 Oct 2026). Its help center says it does not offer a public-facing API, and the only API, SimpleConnect, lets health plans and employee assistance programs request appointments with in-network clinicians. Setup and FAQ: https://cotlet.dev/integrations/simplepractice-api-mcp-server

    • Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.

      https://cliniko.usefulapi.io/mcp

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes tools from the Ecuro Light API for managing clinical appointments, patient records, and clinic availability. It enables users to perform healthcare management tasks such as scheduling, patient search, and report generation through MCP-compatible clients.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude and other MCP clients to read and update an internal, session-cookie-authenticated enterprise web app that has no API, exposing work-order lookup, pending-work listing, and close-out note creation as typed tools. Endpoints, form fields, and selectors are configurable so it can be repointed at any similar HTML-based system.
      3
      1
      MIT