# Taiwan-Health-MCP [Health: Active]

**Category:** 🧬 Biology & Bioinformatics  
**Repository:** https://github.com/healthymind-tech/Taiwan-Health-MCP  
**GitHub Stars:** 166  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/taiwan-health-mcp

## Description
讓 AI agent 讀懂台灣醫療：63 個 MCP 工具，涵蓋 FHIR R4 / TW Core 驗證、ICD-10、SNOMED CT、LOINC、TFDA 藥品與臨床計算器。MCP server for Taiwan healthcare data.

## Tools
Capabilities this server exposes over MCP:

- **health_check** — Return runtime readiness of the MCP server and every module-backed service. Call this first before any workflow to confirm the required services are online.
- **calculate_chads2_vasc** — CHA₂DS₂-VASc stroke-risk score for non-valvular atrial fibrillation (0–9). Accepts raw age/sex and computes brackets internally; also returns the 2024 ESC CHA₂DS₂-VA adjusted score (sex removed). Decision support only.
- **calculate_wells_pe** — Wells criteria for pulmonary embolism (two-tier + three-tier risk). Binary findings are booleans; heart_rate_bpm is raw and the >100 criterion is computed.
- **calculate_wells_dvt** — Wells criteria for deep-vein thrombosis (two-tier + three-tier risk). All items are binary clinical findings.
- **calculate_das28** — DAS28 rheumatoid arthritis disease activity. formula=esr needs esr (mm/h); formula=crp needs crp (mg/L). Joint counts are 28-joint (0–28); global_health is a 0–100 VAS (not the 0–10 scale CDAI uses). Returns score and activity band (remission/low/moderate/high).
- **calculate_cdai** — CDAI (lab-free) rheumatoid arthritis disease activity (0–76). Tender and swollen counts use the 28-joint assessment (0–28 each); patient and provider global assessments are 0–10.
- **calculate_bmi** — Body mass index with Taiwan (Asian) cutoffs: <18.5 underweight, 18.5–23.9 normal, 24–26.9 overweight, ≥27 obese. Height in cm (not metres), weight in kg.
- **calculate_egfr** — Estimated glomerular filtration rate using the CKD-EPI 2021 creatinine equation (race-free), adults ≥18 only. serum_creatinine_mgdl in mg/dL (convert µmol/L by dividing by 88.4). Returns eGFR in mL/min/1.73m² and KDIGO CKD stage.
- **calculate_has_bled** — HAS-BLED bleeding risk on oral anticoagulation (0–9). Accepts raw age (the >65 criterion is computed) and raw systolic BP (the H criterion is computed as SBP >160 mmHg). Returns score and high/low bleeding-risk category (≥3 high).
- **calculate_curb65** — CURB-65 community-acquired pneumonia severity (0–5). BUN in mg/dL (threshold >19), respiratory rate ≥30, hypotension SBP<90 or DBP≤60, confusion, age ≥65.
- **calculate_qsofa** — qSOFA sepsis screening (0–3): respiratory rate ≥22, altered mentation (GCS <15), systolic BP ≤100. ≥2 suggests sepsis and further evaluation.
- **calculate_gcs** — Glasgow Coma Scale (3–15). eye_response 1–4, verbal_response 1–5, motor_response 1–6. Returns total, E/V/M sub-scores, and mild/moderate/severe severity (≤8 severe).
- **list_fhir_servers** — List admin-configured external FHIR servers available for MCP workflows. Discovery entry point — returns {count, servers:[...]} with identity, capabilities, non-sensitive auth metadata, and the last stored probe. Secrets are never returned.
- **get_fhir_server_status** — Get the status and configuration of ONE admin-configured external FHIR server (same fields as list_fhir_servers). Does not make a live call — returns the last stored probe. Secrets are never returned.
- **crud_fhir_server** — Perform a controlled FHIR REST operation against an admin-configured server. Never accepts arbitrary URLs; builds standard FHIR paths from operation/resource_type/resource_id. Write ops require confirm_write=true and must be in the server's allowed set.
- **search_medical_codes** — Search ICD-10-CM diagnosis codes and ICD-10-PCS procedure codes (the editions loaded on this server; see health_check.terminology). diagnosis: hybrid BM25 + vector embedding re-ranking; procedure: BM25 only; all (default): both, returned under separate diagnoses/procedures keys. Results are ranked by relevance, not alphabetical. Optional system: icd10cm | icd10pcs, or any CodeSystem of an installed FHIR IG (canonical URL, id, or name words, e.g. nhi_payment = TW Core medical-service-payment-tw, the Taiwan NHI payment / fee-schedule codes for lab tests and procedures). For an IG CodeSystem the keyword may be Chinese or English free text, an abbreviation or chart wording; results carry code, display, matched_term and same-group siblings. fhir_normalize_code(text, system) does the same within an IG; fhir_lookup_code gives the display of a known code.
- **infer_complications** — Explore the ICD-10-CM hierarchy for a diagnosis code or category prefix. Pure hierarchy lookup: parent codes expand to child codes; leaf codes list siblings.
- **get_nearby_codes** — Retrieve the two ICD-10-CM codes immediately before and after a known code (alphabetical ordering neighbors, not semantic matches).
- **check_medical_conflict** — Fetch full metadata for one diagnosis + one procedure code side-by-side for coding QA / conflict analysis. Returns facts only, no pass/fail verdict.
- **browse_icd_category** — Browse ICD-10-CM structure by chapter or 3-character category. Omit category to enumerate all categories with counts; pass a category to expand it into codes.
- **search_loinc** — Discover LOINC codes and categories with mode-specific search behavior. code (default): hybrid BM25 + semantic search by test name/abbreviation/analyte (optional category narrows to a LOINC class). category: list or filter categories. specimen: search by specimen/system type. component: search by analyte. keyword is required for code/specimen/component modes.
- **interpret_lab_result** — Interpret one lab result against the applicable age/gender-stratified LOINC reference range. Returns the range, the measured value, and a normal/high/low flag. Reference values are general guidance only.
- **batch_interpret_lab_results** — Interpret a full panel of lab results against LOINC reference ranges in one call. results_json must be a JSON array of {loinc_code, value} objects; passing a non-array returns an error without calling the service.
- **query_loinc** — Look up a known LOINC code for full detail or age/gender-stratified reference range. Use after you already know the LOINC code; for discovery use search_loinc.
- **search_snomed_concept** — Search SNOMED CT International Edition by English term (hybrid BM25 + semantic). Returns up to limit closest concepts with concept_id, fsn, preferred_term, active, and hierarchy_tag. For full detail use query_snomed_concept.
- **query_snomed_concept** — Fetch a SNOMED CT concept with optional IS-A hierarchy expansion (ancestors + children). The preferred entry point when you want the concept record AND its surrounding tree.
- **get_snomed_relationships** — Get the clinical attribute relationships (non-IS-A) for a SNOMED CT concept, grouped by relationship type with a human-readable label and list of target concepts.
- **query_snomed_mapping** — Map between ICD-10-CM codes and SNOMED CT concepts (bidirectional). mode=icd: keyword is an ICD-10 code → mapped SNOMED concepts. mode=snomed: keyword is a numeric concept_id or English term → mapped ICD-10 codes.
- **search_drug** — Search Taiwan FDA drug records by mode. drug_name (default), ingredient, license_id, atc_code. Output: { mode, keyword, include_cancelled, results }.
- **identify_unknown_pill** — Identify a Taiwan FDA drug by pill appearance keywords (space-separated), matched conjunctively against appearance fields with a small color/shape synonym map.
- **get_drug_details** — Return the canonical normalized drug record for one Taiwan FDA license, augmented with stage availability and document counts.
- **get_drug_asset_links** — Return persisted asset metadata plus runtime-generated MinIO download links (presigned URLs are null when MinIO is unconfigured).
- **fhir_list_igs** — List the FHIR Implementation Guide (IG) packages installed on this server (isDefault, installOrigin manual|dependency, dependencies). Tools that omit package_id use the package owning the canonical / meta.profile involved, else the default IG. compact=true: just packageId#version → title by install origin, plus the default IG.
- **fhir_get_ig** — Details of one IG package: identity, dependencies, and per-resource-type artifact counts. data.deps_missing lists declared dependencies that are not installed (incomplete closure).
- **fhir_list_artifacts** — List an IG's conformance artifacts (StructureDefinitions, ValueSets, CodeSystems, examples) as summary rows. Without package_id only the default IG is listed; all_packages=true lists every installed package. Zero rows comes with data.hint naming the other packages that match. compact=true returns id → title per resource type (about a fifth of the size) instead of full summary rows.
- **fhir_search_artifacts** — Full-text search an IG's artifacts by id / canonical URL / name / title / description. Without package_id only the default IG is searched; all_packages=true searches every installed package. Zero hits comes with data.hint naming the other packages that match (e.g. Claim → the PAS IG). compact=true returns id → title per resource type instead of full summary rows.
- **fhir_list_resource_profiles** — List the IG's selectable resource Profiles (constraint StructureDefinitions), grouped by base FHIR resource type. Without package_id: the default IG (all_packages=true: every installed package; zero rows → data.hint). After choosing one, call fhir_get_profile_required_elements to learn exactly which elements it requires. compact=true (recommended when tool output is limited, e.g. all of TW Core: ~4k instead of ~13k chars) returns per base type a map profile id → title plus the canonical base; pass base_type to narrow further.
- **fhir_rank_resource_profiles** — Rank candidate Profiles by how many of your source-data field keys match each profile's element paths. Suggests only (selectionRequired:true).
- **fhir_get_profile** — Summary of one Profile / StructureDefinition: identity, base definition, derivation, element count. identifier may be an id or a canonical URL, optionally pinned as 'url|version' (an uninstalled version is ARTIFACT_NOT_FOUND).
- **fhir_get_profile_elements** — Read a Profile's StructureDefinition snapshot via a view: elements | element | slices | choices | binding | examples. path is required for element/slices/choices/binding. Raw min is per element and ignores parent optionality — for the effective required set use fhir_get_profile_required_elements.
- **fhir_get_profile_required_elements** — Return every element a profile effectively requires (min>=1 with required ancestors, required slices, choice types, invariant-implied value-or-dataAbsentReason) plus target-implied primary content, each classified as auto, coding, source_fact, workflow_default, derived, ... with cardinality, type, binding, fixed/pattern, mustSupport and a short fill hint. derived rows (e.g. Condition.category) carry allowedCodes and a derivation rule in `hint` (Condition.category: encounter-diagnosis for this visit's diagnoses, problem-list-item only for a longitudinal problem list). mustSupport is NOT required: unlisted and optional:true rows may be left out — never refuse a task because one is missing. Use it before writing a resource so every required field is filled; works for any installed IG (without package_id the package owning the profile is used; 'url|version' pins a version). Profiled extensions are expanded from their definitions, and profile-specific error invariants are listed under `invariants`. verbosity='compact' (default) keeps id/required_by/grounding_class/fixed|pattern|value/choices/allowedCodes/hint and folds profile-pinned subtrees into one copyable `value`; verbosity='full' adds min/max/types/binding/mustSupport per row.
- **fhir_get_valueset** — Return a ValueSet's definition (compose block + metadata) without expanding it.
- **fhir_expand_valueset** — Expand a ValueSet to its member codings, resolved locally where possible. Whole large external systems are not enumerated (TOO_BROAD).
- **fhir_lookup_code** — Look up the display/definition of a (system, code) pair from locally held terminology.
- **fhir_validate_code** — Check whether a (system, code) is a member of a ValueSet. Returns valid | invalid | unverifiable. value_set may be pinned as 'url|version'.
- **fhir_normalize_code** — Turn free text into ranked candidate codes for a target system or ValueSet (ConceptMap + lexical + semantic). Provide at least one of value_set or system. Supported: SNOMED CT, LOINC, ICD-10-CM/PCS and every CodeSystem of an installed IG (e.g. TW Core medical-service-payment-tw = Taiwan NHI payment codes for lab tests and procedures, occupation, department codes). For IG CodeSystems the text may be Chinese or English, an abbreviation or chart wording (CRP, TKA, 清創縫合 …); system may also be the CodeSystem id or alias words (nhi_payment). Candidates carry matched_term / matched_language and same-group siblings (e.g. the same test by another method). Drugs: Taiwan NHI drug codes (健保藥品代碼) ARE supported — system='medication-nhi-tw' (TW Core) or 'nhi-medication' (TWPAS), text = brand or generic name in English or Chinese, strength optional (e.g. 'Glucophage 500mg', '脈優錠 5mg', 'amlodipine'); when the default IG ships only an excerpt of a CodeSystem the full installed copy is searched (see warnings / codesystem_copies). ATC: WHO ATC (http://www.whocc.no/atc) is not held as a searchable CodeSystem (TW Core medcation-atc-tw has only 27 Taiwan-specific codes); find the NHI drug instead — its candidate's `linked` lists the drug's ATC code (e.g. {system:'http://www.whocc.no/atc', code:'A10BA02'}). TFDA licence numbers: system='medication-fda-tw'. Taiwan FDA product details (ingredients, inserts): search_drug / get_drug_details.
- **fhir_resolve_reference** — Mint (or return) a stable urn:uuid reference for a logical key within a build context, so resources can reference each other before finalization.
- **fhir_build_bundle** — Assemble inline FHIR resources into a Bundle, wiring urn:uuid references. Each entry is {resource, key?, fullUrl?, request?}.
- **fhir_validate_resource** — Validate a FHIR resource against an IG profile, in-process (source:builtin). Pre-flight only. Optional source_text/site_config/evidence_map add grounding issues for this resource (is each value stated in the record). Without package_id the IG owning its meta.profile is used ('|version' pins a version; provenance.resolved_by). Issues may carry ranked suggestions [{value, kind, confidence, reason, patch}] (what to change the value to).
- **fhir_validate_bundle** — Validate a FHIR Bundle in-process: each entry's resource against its meta.profile plus internal reference integrity. Optional source_text/site_config/evidence_map add grounding issues (is each value stated in the record). Without package_id the IG owning the meta.profile canonicals is used ('|version' pins a version; provenance.resolved_by). Issues may carry ranked suggestions [{value, kind, confidence, reason, patch}] (what to change the value to) and, for reference-chain errors, caused_by.
- **fhir_check_grounding** — Deterministic faithfulness check of a Bundle against the source clinical record: every populated clinical fact and code must be supported by record text (evidence map or auto-locate), with date/number/unit/identifier/dose/frequency normalisation and section, negation and history rules. Returns issues in the fhir_validate_bundle shape. No LLM.
- **fhir_check_completeness** — Gap report: compare the facts that the conversion targets require (profile-required plus target-implied elements) with what the record states, and return the missing items, the record lines that state absence, a template clarification question and a ready insufficient_information object. Deterministic, no LLM.
- **fhir_get_resource_skeleton** — Get a blanked, annotated fill-form for authoring a resource against a profile (paths, cardinality, types, candidate codes, examples). Each field's `required` is the element's own min>=1; `effectiveRequired` also requires every ancestor to be required. For the complete required list (slices, invariants, where each value comes from) call fhir_get_profile_required_elements.
- **fhir_finalize_resource** — Finalize an LLM-filled draft: pin mechanical fields (fixed/pattern/meta.profile), infer single-system codings, wire references, generate narrative, then validate. Does not auto-loop.
- **query_fhir_condition** — Generate a FHIR R4 Condition resource from an ICD-10-CM code or a diagnosis keyword. Provide exactly one of icd_code (Path A — full field support) or diagnosis_keyword (Path B — search-first; only patient_id/clinical_status/verification_status/severity applied).
- **validate_fhir_condition** — Validate a FHIR R4 Condition resource for required fields (resourceType/code/subject) and status presence. Basic structural validation only.
- **query_fhir_medication** — Generate a FHIR R4 Medication or MedicationKnowledge resource for a TFDA drug. Provide exactly one of license_id (Path A — direct) or keyword (Path B — search-first). Derived from normalized TFDA data only (no RxNorm).
- **validate_fhir_medication** — Validate structure and core field semantics of FHIR Medication / MedicationKnowledge resources (resourceType, code.coding, ingredient items). Basic validation only.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What Taiwan-Health-MCP MCP server does

Taiwan-Health-MCP MCP server gives agents a single MCP interface for Taiwan-focused healthcare data and common clinical terminology. Its tool groups cover ICD-10-CM and ICD-10-PCS, SNOMED CT International, LOINC, RxNorm, FHIR R4 and Taiwan FHIR implementation guides, Taiwan FDA drug records, and clinical calculators. The repository describes 63 tools, although module-dependent tools can be unavailable when their source data has not been loaded.

The server includes read-oriented tools for code search, hierarchy browsing, terminology mapping, laboratory interpretation, drug lookup, and FHIR profile or resource operations. It also includes calculators for CHA₂DS₂-VASc, Wells PE and DVT, DAS28, CDAI, BMI using Taiwan cutoffs, CKD-EPI 2021 eGFR, HAS-BLED, CURB-65, qSOFA, and GCS.

## How it works

The application is built with the official TypeScript MCP SDK and runs on Node.js. A hosted streamable-HTTP endpoint is available at `https://tw-health-mcp.healthymind-tech.com/mcp`. Self-hosted deployments expose the MCP endpoint through nginx, with the application, worker, PostgreSQL 16 with pgvector, Redis, and MinIO running as Docker Compose services.

Search behavior depends on the module and its indexed data. ICD-10, LOINC, SNOMED CT, and installed FHIR Implementation Guide code systems can use hybrid keyword and embedding search. If embeddings are incomplete or unavailable, searches fall back to keyword or BM25 behavior. `health_check` reports runtime readiness and module-backed service status and should be called before a workflow.

FHIR server operations use administrator-configured external servers rather than arbitrary URLs. `list_fhir_servers` and `get_fhir_server_status` expose stored configuration and probe information without returning secrets. `crud_fhir_server` constructs standard FHIR paths and restricts writes to an allow-list; create, update, patch, and delete operations require `confirm_write=true`.

## Setup and configuration

For a local deployment, clone the repository, copy `.env.example` to `.env`, configure values such as the database password and administrator settings, then run `docker compose up -d`. After startup, use `http://<host>:8080/mcp` for MCP traffic and `http://<host>:8080/admin` for the administration interface. The application container is internal; traffic should go through nginx and the configured `WEB_PORT`.

Administrators must use the backend to import source data before relying on module-specific tools. The administration interface also manages FHIR server registrations, imports, embeddings, and related module status. Exact environment variable names and deployment options should be taken from the repository’s `.env.example` and deployment documentation.

## Tools and capabilities

Taiwan-Health-MCP MCP server includes capabilities for:

- Searching and browsing ICD-10-CM/PCS codes, finding hierarchy relationships, nearby codes, and diagnosis-procedure metadata.
- Discovering LOINC codes, querying details, and interpreting individual or batched laboratory results against reference ranges.
- Searching SNOMED CT concepts, expanding hierarchies, retrieving relationships, and mapping between SNOMED CT and ICD-10-CM.
- Searching Taiwan FDA drugs by name, ingredient, license, or ATC code, including pill identification by appearance keywords.
- Listing configured FHIR servers and performing controlled FHIR REST operations.
- Reading FHIR terminology and profile artifacts, validating resources and bundles, and checking grounding or completeness where the corresponding module is loaded.
- Running deterministic clinical scoring and measurement calculations.

## Limitations and notes

Calculator outputs are decision-support results, not diagnoses. Laboratory reference ranges are general guidance, and code-conflict checks return facts without a pass/fail judgment. Input units and scales matter: height for BMI is in centimeters, eGFR creatinine is in mg/dL, DAS28 global health uses a 0–100 VAS, and CDAI global assessments use 0–10.

Only `crud_fhir_server` can write to an external FHIR server, and those writes remain subject to administrator configuration and explicit confirmation. Other tools are read-only. Tool availability indicates that source data is loaded; it does not guarantee that embeddings are complete. Search responses can identify keyword-only fallback behavior.

_Full upstream README: https://allmcps.com/mcp/taiwan-health-mcp/readme_