sns-portugal-mcp
Read-only, keyless MCP server for official monthly SNS Portugal open-data statistics, plus dataset search and custom querying.
Find SNS hospitals/ULS by name or nearest coordinate, including whether they report emergency, consultation, or surgery data and their
stats_entitymapping.Retrieve emergency-department visits by type and Manchester triage colour for an institution, region, or mainland Portugal, with monthly and year-to-date values.
Retrieve surgery access metrics: surgical waiting list (LIC), TMRG compliance, mean days before surgery, and scheduled/urgent surgeries performed.
Retrieve hospital outpatient consultation volumes and first-specialist-consultation TMRG compliance.
Search the ~149 SNS Transparency portal datasets by Portuguese keyword.
Run custom ODSQL queries on any portal dataset using
where,select,group_by,order_by,limit, andoffset.Note limits: official/provisional statistics, not live emergency waits; no specialty breakdown; live waits are directed to tempos.min-saude.pt.
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., "@sns-portugal-mcp How many emergency visits did Santa Maria have last month, by triage colour?"
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.
sns-portugal-mcp
Deprecated — use portugal-mcp instead. This server now lives on as the saude feature of portugal-mcp, together with IPMA weather, INE, Banco de Portugal, Parliament, public contracts and more. Install with uvx portugal-mcp (add PORTUGAL_MCP_FEATURES=saude to load only this part). Tool names: find_institutions → sns_find_institutions, emergency_stats → sns_emergency_stats, surgery_wait_stats → sns_surgery_wait_stats, consultation_wait_stats → sns_consultation_wait_stats, search_datasets → sns_search_datasets, query_dataset → sns_query_dataset. This repository gets no further updates.
MCP server for official open-data statistics about Portugal's national health service (SNS), so Claude (or any MCP client) can answer "how busy is the emergency department at Santa Maria?", "how many people are waiting for surgery in the Norte region?" or "which SNS hospitals are near me?".
Read-only, no key, no account. It uses only public open data. Not affiliated with the SNS, SPMS or the Portuguese Ministry of Health.
Statistics, not the live queue. The figures are official monthly statistics; the newest month is usually 2-3 months old and provisional. This server does not show live emergency-room waiting times. For those, see tempos.min-saude.pt.
Not medical advice. In an emergency call 112. For health advice call SNS 24 on 808 24 24 24.
Tools
find_institutions
Finds SNS hospitals and local health units (ULS) by name, or the nearest ones to a coordinate. Each result says whether the place reports emergency, consultation and surgery data, and gives stats_entity: the name the statistics use for it. Statistics are published per ULS or hospital group, not per building.
Parameters: query (name, accent-insensitive), lat / lon (sort by distance), emergency_only, limit.
emergency_stats
Emergency-department visits per month, by type (general, paediatric, obstetric, psychiatric) and by Manchester triage colour (red, orange, yellow, green, blue, white, not triaged), with each colour's share of the month. Covers one institution, one region, or the whole country.
Parameters: institution, region (Norte | Centro | LVT | Alentejo | Algarve), period ("YYYY-MM", latest month to include), months (default 6).
surgery_wait_stats
Surgery access per month:
the surgical waiting list (LIC) at month end;
the % of waiting patients still within the legal maximum guaranteed time (TMRG);
the mean days from hospital admission to the operation (scheduled inpatient surgery);
surgeries performed: scheduled (inpatient and day surgery) and urgent.
Same parameters as emergency_stats. The open data has no breakdown by specialty.
consultation_wait_stats
Hospital outpatient consultations per month (first and follow-up), plus the % of first specialist consultations (referred by a family doctor) held within the TMRG. Same parameters as above.
search_datasets
Searches the 149 datasets of the SNS Transparency portal by keyword. Titles are in Portuguese, so Portuguese keywords work best: "ocupação", "partos", "rastreios", "SNS 24", "INEM". Returns each dataset's id, description and field names.
query_dataset
Runs an ODSQL query (where, select, group_by, order_by, limit, offset) on any portal dataset. Use it for anything the tools above don't cover.
Year-to-date values
Most hospital-activity datasets publish year-to-date cumulative values, so the December figure is the annual total. The curated tools return both the year-to-date value and a derived in_month value (this month minus the previous one). If you use query_dataset directly, do that subtraction yourself.
Related MCP server: mcp-cnes
Install
Quickest (needs uv): no clone needed, it runs straight from PyPI.
claude mcp add sns-portugal -- uvx sns-portugal-mcpFor Claude Desktop, use "command": "uvx", "args": ["sns-portugal-mcp"].
From source:
Requires Python 3.10+.
git clone https://github.com/ThiagoJacobLannes/sns-portugal-mcp
cd sns-portugal-mcp
python -m pip install -e .On Windows, if you keep code in a cloud-synced folder (Google Drive, OneDrive), create the virtual environment outside it. Sync clients drop desktop.ini files into folders, which can crash packages on startup.
Add to Claude Code
claude mcp add sns-portugal -- python -m sns_portugal_mcp.serverAdd to Claude Desktop
Merge claude_desktop_config.snippet.json into your Claude Desktop claude_desktop_config.json, then restart Claude Desktop:
{
"mcpServers": {
"sns-portugal": {
"command": "python",
"args": ["-m", "sns_portugal_mcp.server"]
}
}
}Data sources
Source | What it gives | Access | Licence / terms |
149 datasets of monthly SNS statistics, published by the SNS Executive Direction (DE-SNS) | Open, no key | No licence is set in any dataset's metadata (checked 2026-10-31). The portal's terms allow reuse under Portuguese public-sector-information law (Lei n.º 26/2016): cite the source, keep the data's integrity and context, and flag any changes you make. Some of the same datasets are mirrored on dados.gov.pt; there, some copies are marked CC-BY and others "not specified". | |
List of hospitals and ULS with coordinates and which data each reports | Public static file, no key | No licence stated. |
Datasets used by the curated tools:
Tool | Datasets |
|
|
|
|
|
|
Data derived from these sources keeps the source's terms. The code in this repository is MIT-licensed.
What this server does not do. It does not call tempos.min-saude.pt/api/*: that API needs a key embedded in the site's own web app, and this server does not use other people's keys. It also does not scrape the live waiting-time report (an embedded Power BI report).
How it works
The server calls the portal's public Explore API with httpx and aggregates in the query itself (group_by tempo, sum(...)), so regional and national totals are computed on the server side. Hospital names are matched without regard to accents. A hospital such as "Hospital de Faro" is mapped to the ULS it reports under ("ULS do Algarve") using the institution list. The dataset catalog, the institution list and the institution names are cached in memory for 6 hours. If an upstream call fails or a query is malformed, the tool returns a clear {"error": ...} and does not guess.
Environment overrides (optional): SNS_ODS_BASE_URL, SNS_INSTITUTIONS_URL.
License
MIT
Available Tools
6 toolsconsultation_wait_statsA
Hospital outpatient consultations per month and the % of FIRST specialist consultations (referred by a family doctor via CTH/SIGA) held within the guaranteed maximum time (TMRG).
Use for "how long is the wait for a first hospital appointment at X?", "is hospital Y on time with first consultations?", "how many consultations did the Centro region do?". Official monthly statistics (latest month usually 2-3 months back, provisional); there is no breakdown by specialty in the open data.
Per period (latest first): consultations_in_month / _year_to_date (total, first, subsequent) and first_consultations_within_max_time_pct for the month and year-to-date.
Args: institution: Hospital or ULS name; mapped to its ULS. region: Norte | Centro | LVT (Lisboa) | Alentejo | Algarve. Ignored if institution is given. period: Latest month to include, "YYYY-MM" (default: newest available). months: How many months back (default 6, max 24).
Inputs: months, period, region, institution. Returns: object
emergency_statsA
Emergency-department (urgência) visits per month: by type and by Manchester triage colour.
Use for "how busy is the ER at X?", "how many emergency visits in the Algarve last month?", "what share of ER visits are green/blue (non-urgent)?". OFFICIAL MONTHLY STATISTICS ONLY — not the live queue (the latest month is usually 2-3 months back and provisional). For live waiting times send the user to https://tempos.min-saude.pt. Not medical advice: in an emergency call 112; SNS 24 (808 24 24 24) for advice.
Scope: one institution, one region, or (neither) all of mainland Portugal's SNS hospitals.
Per period (latest first): visits_in_month and visits_year_to_date by type (general, paediatric, obstetric, psychiatric, total), triage_in_month by colour (red = immediate, orange = very urgent, yellow = urgent, green = less urgent, blue = non-urgent, white = not clinical / other) and triage_share_in_month_pct.
Args:
institution: Hospital or ULS name, accent-insensitive ("Santa Maria", "São João",
"Hospital de Faro"). A hospital is mapped to its ULS; check scope.
region: Norte | Centro | LVT (Lisboa) | Alentejo | Algarve. Ignored if institution is given.
period: Latest month to include, "YYYY-MM" (default: newest available).
months: How many months back to return (default 6, max 24).
Inputs: months, period, region, institution. Returns: object
find_institutionsA
Find SNS hospitals / local health units (ULS) by name, or the nearest ones to a coordinate.
Use this first when the user names a hospital or a place ("hospitals near Lisbon",
"is there an emergency department near 38.72,-9.14?"), then pass stats_entity to
emergency_stats / surgery_wait_stats / consultation_wait_stats.
Each result: name, its parent ULS, coordinates, distance_km (when lat/lon given), whether
it reports emergency / consultation / surgery data on tempos.min-saude.pt, and
stats_entity — the name under which the official statistics report it (statistics are
per ULS / hospital group, not per building). This list does NOT contain live waiting times;
for live emergency waits send the user to https://tempos.min-saude.pt.
Args:
query: Part of the name, accent-insensitive, e.g. "Santa Maria", "Faro", "ULS Algarve".
lat, lon: Sort by distance from this point (WGS84), e.g. Lisbon 38.7223, -9.1393.
Without query, umbrella ULS entries are skipped (they duplicate a hospital's location).
emergency_only: Only places that report emergency-department data.
limit: Max results (default 10, max 50).
Inputs: lat, lon, limit, query, +1 more. Returns: object
query_datasetA
Run an ODSQL query on any SNS Transparency portal dataset (Opendatasoft Explore API v2.1).
Use after search_datasets for anything the curated tools don't cover. Clauses are ODSQL:
where:
instituicao like "santa maria" and tempo >= date'2026-01-01'(likeis a case- and accent-insensitive "contains"; dates use date'YYYY-MM-DD')select:
tempo, instituicao, total_urgenciasor aggregatessum(total_urgencias) as totalgroup_by:
regiaoortempo(combine with aggregates in select)order_by:
tempo descMost hospital-activity datasets (fieldtempo, monthly) store YEAR-TO-DATE CUMULATIVE values: December is the annual total; a single month = this month minus the previous one. Many datasets have aregiaoand aninstituicao(orentidade) field. Official statistics, not live data.
Args: dataset_id: e.g. "ocupacao-do-internamento" (from search_datasets). where, select, group_by, order_by: ODSQL clauses (optional). limit: Rows to return (default 20, max 100). offset: Skip rows, for paging.
Inputs: dataset_id (required), limit, where, offset, +3 more. Returns: object
search_datasetsA
Search the ~150 datasets of the SNS Transparency portal (titles and descriptions are in Portuguese).
Use when the curated tools don't cover the question — e.g. hospital bed occupancy ("ocupação"), births/caesareans ("partos"), INEM pre-hospital calls, SNS 24 calls, family doctor coverage ("médico de família", "inscritos"), medicines spending, staff ("trabalhadores"), cancer screening ("rastreios"). Then call query_dataset with the dataset_id and the field names returned here. Portuguese keywords work best; matching is accent-insensitive.
Args: query: Keywords, e.g. "ocupação internamento", "partos", "urgência". Empty = list all (id + title). limit: Max results (default 10, max 50; ignored when listing all).
Inputs: limit, query. Returns: object
surgery_wait_statsA
Surgery access indicators per month: surgical waiting list, % within the guaranteed maximum time, mean days from admission to surgery, and surgeries performed.
Use for "how long is the wait for surgery at X?", "how many people are on the surgery list in the Norte region?", "how many operations did hospital Y do?". Official monthly statistics (latest month usually 2-3 months back, provisional). The open data has NO breakdown by specialty or procedure — say so if asked for one.
Per period (latest first):
waiting_list: patients on the surgical waiting list (LIC) at month end, how many are still within the legal maximum guaranteed response time (TMRG, 180 days for normal priority since 2018) and the % within it.
mean_days_before_surgery_in_month / _year_to_date: average days between hospital admission and the operation for scheduled inpatient surgery (this is NOT the time on the waiting list).
surgeries_in_month / surgeries_year_to_date: scheduled (= inpatient + day surgery) and urgent.
Args: institution: Hospital or ULS name ("Santa Maria", "Coimbra", "IPO Porto"); mapped to its ULS. region: Norte | Centro | LVT (Lisboa) | Alentejo | Algarve. Ignored if institution is given. period: Latest month to include, "YYYY-MM" (default: newest available). months: How many months back (default 6, max 24).
Inputs: months, period, region, institution. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct role: find_institutions resolves names/places, the three *_stats tools cover separate official-statistics domains, and search_datasets/query_dataset form a clear metadata-search-then-query pattern. The descriptions explicitly guide agents to start with curated tools and fall back to generic dataset tools only when needed, so overlap is minimal.
All names use snake_case and are readable, but the set mixes two patterns: verb_noun action tools (find_institutions, search_datasets, query_dataset) and noun_stats statistics tools (emergency_stats, surgery_wait_stats, consultation_wait_stats). The conventions are internally predictable within each group, with only minor deviation from a single uniform pattern.
Six tools is well-scoped for an official SNS statistics server: one resolver, three curated statistics endpoints, and two generic dataset tools. None of the tools appear redundant, and the count is far from thin or unwieldy.
The surface covers institution lookup, the main curated hospital-activity domains (emergency, surgery, consultations), and arbitrary access to the remaining SNS Transparency datasets via search_datasets and query_dataset. Live waiting times are explicitly out of scope and users are directed to the official website, so there are no obvious dead ends for the stated purpose.
Related MCP Connectors
Portugal public data: weather, INE, Parliament, contracts, SNS, fuel, transit, power cuts.
Official public data as MCP tools: EU/US tenders, NPI Registry, UK Companies House, Mexico data.
Experimental MCP providing read-only population statistics from Eurostat.
Keyless MCP access to official Luxembourg public data: laws, statistics, mobility, and more.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for accessing BPstat (Banco de Portugal) statistics API without API keys. Enables querying Portuguese central bank data through natural language.90 npmMIT
- AlicenseAqualityCmaintenanceMCP server for loading and querying public data from the Brazilian National Registry of Health Establishments (CNES). It enables natural language searches for health facilities by municipality, CNES code, or state, along with statistics and data loading.6MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying the Brazilian government's transparency portal (Portal da Transparência) to search official public spending and transparency data. Read-only access via natural language from any MCP client, with prepaid pay-per-query usage.MIT

cat.idescat/mcpofficial
AlicenseNot gradedqualityCmaintenanceEnables any MCP client to discover and query official Catalonia statistics through read-only tools and resources, including statistic catalogues, table metadata, filtered JSON-stat data, territorial breakdowns, and Markdown tables with source attribution.1MIT