jcs-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jcs-mcp Show me my upcoming appointments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Authenticate; session saved to |
| Name, email, patient ID |
| Main health feed — exam results, appointment confirmations, documents |
| Notifications and messages |
| Full message detail; body contains signed document URIs |
| Upcoming and recent appointments from the calendar |
| Active (and optionally expired) prescriptions |
| Invoices (Faturas/Recibos) from the patient profile |
| Fetch HTML exam result content from a signed URI |
| Download a PDF document, saved to |
| 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+
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 syncConfiguration
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=./downloadsAuth 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:
Open Chrome DevTools → Application → Local Storage →
https://webapp.jcs.ptFind the key that contains your
appUuid— this is yourJCS_DEVICE_UUIDOpen DevTools → Network, log in normally, and look for the
POST /api/device/tokenresponse — thedeviceTokenfield is yourJCS_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.pyStandalone
uv run python mcp_server.pyFirst-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.ptAuth: OAuth2 password grant via
POST /Tokenwithuid,AppUuid, anddtkcustom headersAll data endpoints use
POSTwith a JSON body containingdevice(the appUuid)Document URIs are signed, time-limited tokens embedded in message body HTML as
data-attach-htmlattributesHTML exam results:
GET /api/attachdata/getcontent?uri=...PDF documents:
GET /api/attachdata/getfile?uri=...
License
MIT
Available Tools
11 toolsdownload_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
Scored across 11 tools
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.
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.
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.
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
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.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceExposes 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.-
- FlicenseAqualityDmaintenanceEnables users to interact with the CUF health portal to retrieve patient information, appointments, clinical documents, invoices, and prescriptions through natural language.122-
- FlicenseNot gradedqualityDmaintenanceExposes Garmin Connect health data (steps, sleep, HR, HRV, stress, activities, etc.) as tools for MCP-compatible clients like Claude.-
- AlicenseAqualityCmaintenanceEnables 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.31MIT