Taiwan Health MCP Server

https://github.com/user-attachments/assets/13527dd9-72ac-4e36-9868-7967399d4041

以官方 TypeScript MCP SDK（@modelcontextprotocol/sdk）建構的 Node.js 伺服器，對外提供 70 個工具，涵蓋 12 個工具群組。專為高吞吐量的生產級 SaaS 部署設計。

快速連線

不想自己架設，可以直接連官方端點 https://tw-health-mcp.healthymind-tech.com/mcp（MCP streamable-http）。

Claude Code

claude mcp add --transport http taiwan-health https://tw-health-mcp.healthymind-tech.com/mcp

Claude Desktop / claude.ai：在「設定 → 連接器」新增自訂連接器，貼上上面的端點網址。

其他支援 MCP streamable-http 的客戶端，填入同一個網址即可。要在自己的環境部署，請看自行部署。

Related MCP server: FHIR MCP Server

六大面向

FHIR Box 連接 · 3 個工具

管理者登錄院內 FHIR Box 或任何 FHIR R4 伺服器後，AI agent 就能查詢與讀取資源

crud_fhir_serverget_fhir_server_status

文件 →

TW IG 驗證與 grounding · 26 個工具

多 IG 剖面與 ValueSet、骨架填值產生資源、對齊 HL7 validator_cli 7.0.1 的驗證，以及不靠 LLM 的病歷忠實度檢查

fhir_validate_resourcefhir_check_grounding

文件 →

台灣藥品與營養 · 9 個工具

TFDA 藥品許可證、仿單 OCR、依刻字 / 顏色 / 外型辨識藥丸，加上健康食品與食品營養成分

identify_unknown_pillquery_food_nutrition

文件 →

國際語彙 · 13 個工具

ICD-10-CM / PCS（CMS 2026-04-01）、SNOMED CT International、LOINC 2.80 與 RxNorm：查碼、跨語彙映射、解讀檢驗值

search_medical_codesinterpret_lab_result

文件 →

臨床計算器 · 11 個工具

CHA₂DS₂-VASc、Wells、HAS-BLED、CURB-65、qSOFA、GCS、eGFR、DAS28、CDAI、BMI（台灣切點）；確定性計算，不讓 LLM 自己算

calculate_egfrcalculate_chads2_vasc

文件 →

語意搜尋 · 跨模組

ICD-10、LOINC、SNOMED CT 與 IG CodeSystem 以 pgvector 嵌入（預設 Ollama qwen3-embedding）做混合搜尋；沒有嵌入時自動退回關鍵字搜尋

search_loincfhir_normalize_code

文件 →

• 模組相關工具會依資料載入狀態自動啟用 / 停用（例如健康補充品、食品營養未載入時，/openapi.json 只會列出 58 個）；FHIR 伺服器、臨床計算器與系統工具則永遠註冊。管理後台「MCP 工具」頁（/admin/mcp）列出全部 70 個工具、未註冊的原因，並可線上試呼叫。

• 除 crud_fhir_server 外，所有工具皆為唯讀。crud_fhir_server 可對已由管理者登錄的外部 FHIR 伺服器執行寫入（create / update / patch / delete），且必須該伺服器的 allow-list 允許、呼叫端並帶入 confirm_write=true。

• 工具顯示為 available 只代表來源資料已載入，不代表 embedding 已完整。請在管理後台各模組頁（如「醫療術語」底下的 ICD-10 / LOINC / SNOMED）檢查 Embeddings 計數；未完成時搜尋會退回或混用 keyword/BM25（回應會標 search_mode: "keyword_only"）。

• 術語範圍：ICD-10-CM（CMS 2026-04-01 完整碼表，含第 7 碼）/ ICD-10-PCS、WHO ICD-10（選用）、SNOMED CT International（含 inactive 內容與歷史關聯）、LOINC 2.80（含 answer / part / panel）、RxNorm、FHIR R4；內建 validator 另支援 CVX、ISO 3166、UCUM。Validator 稽核見 node-server/scripts/validator-audit/。

架構

flowchart LR
  subgraph clients["客戶端"]
    agent["AI agent<br/>Claude · ChatGPT · Cursor"]
    openapi["OpenAPI 客戶端<br/>Open WebUI"]
    admin["管理者"]
  end
  subgraph stack["docker compose"]
    nginx["nginx :8080<br/>單一入口"]
    app["app<br/>MCP server + 管理 API"]
    web["web-v2<br/>管理後台 SPA"]
    worker["admin-worker<br/>匯入與嵌入"]
    pg[("PostgreSQL 16 + pgvector<br/>經 pgBouncer")]
    redis[("Redis<br/>即時事件")]
    minio[("MinIO<br/>來源檔與藥品資產")]
    nginx --> app
    nginx --> web
    app --> pg
    worker --> pg
    app <--> redis
    worker <--> redis
    worker --> minio
  end
  agent -- "/mcp" --> nginx
  openapi -- "/openapi.json · /tools/*" --> nginx
  admin -- "/admin" --> nginx
  worker -.-> ext["嵌入模型 · OCR · Analysis LM<br/>TFDA Open Data"]
  app -.-> fhir["外部 FHIR 伺服器"]

• 後端全部是 Node.js / TypeScript（node-server/）：app 提供 MCP 與管理 API，admin-worker 執行所有匯入與嵌入工作。本專案已無 Python 執行期相依。

• 管理後台是 Vite + React + Mantine 的 SPA（web-v2/）；舊的 Next.js web/ 只留在 compose profile legacy-web 供回滾。

• 工具依各模組資料載入狀態自動註冊；嵌入模型無法連線時，搜尋自動退回關鍵字。

• 指標以 Prometheus 格式輸出（METRICS_PORT，預設只綁 localhost）。

• 宣傳頁與法務頁（/、/status、/privacy、/dpa）由獨立的官網提供，不在本專案。

自行部署

git clone https://github.com/healthymind-tech/Taiwan-Health-MCP.git
cd Taiwan-Health-MCP
cp .env.example .env                          # 設定 POSTGRES_PASSWORD、ADMIN_* 等
docker compose up -d

啟動後 MCP 端點是 http://<host>:8080/mcp，到 http://<host>:8080/admin 登入管理後台匯入資料。完整說明見部署指南。

舊的 Next.js web 服務屬於 compose profile legacy-web，docker compose up -d 不會啟動它（僅供回滾）。

重要：app 容器不對主機開放 8000 埠，所有流量都必須經過 nginx。請一律使用 http://<host>:8080（或你設定的 WEB_PORT）。

程式碼變更後重新部署：

docker compose build app admin-worker web-v2 && docker compose up -d --no-deps app admin-worker web-v2

admin-worker 是另一個映像（Dockerfile.worker），只重建 app 會讓 worker 繼續跑舊的匯入程式碼。要讓 health_check 回報 git sha，建置時設定環境變數：BUILD_SHA=$(git rev-parse --short HEAD) docker compose build app admin-worker（compose.yaml 會把它當 build arg 傳入，未設定時為 dev）。

資料匯入由 Admin Console 觸發、交由 admin-worker 背景執行（無獨立的 CLI data-loader 容器）。

1. 管理後台預設啟用（ADMIN_ENABLED=true）。在 .env 設定登入資訊：

   ADMIN_USERNAME=admin
   # 首次啟動時以此明文密碼建立帳密（雜湊後存入 admin.admin_credentials，之後不再覆寫；
   # 建立後請刪除這行，改密碼請到管理後台「帳號安全」）。
   ADMIN_INITIAL_PASSWORD=change-me
   # 必改：仍為範例值時伺服器拒絕啟動（openssl rand -hex 32）
   ADMIN_SESSION_SECRET=...

   也可改用 ADMIN_PASSWORD_HASH（sha256$<hex> 或 pbkdf2_sha256$<iterations>$<salt>$<hex>；在 .env 中每個 $ 要寫成 $$）。啟動後（docker compose up -d），於 http://<host>:8080/admin 登入。

2. 在各模組頁（側邊欄「醫療術語」、「藥品」、「健康食品」、「食品營養」、「IG 套件庫」）匯入資料：

   • 需上傳來源檔（上傳後按匯入）：ICD-10-CM（CMS order file zip）/ ICD-10-PCS、WHO ICD-10（選用）、LOINC、SNOMED CT、RxNorm；FHIR IG 可由套件 registry 安裝或上傳 package.tgz（缺少的相依套件會自動下載）。

   • 由 API 自動抓取（直接按匯入或設定排程）：藥品（TFDA，三階段：索引 → 爬取豐富 → OCR/LLM 分析）、健康補充品、食品營養。

3. 嵌入（語意搜尋）為獨立的 *_embed 工作，可於各模組頁面執行。嵌入與分析 LLM 的端點在「模型端點」頁設定（provider 帳號 + 路由，存於 admin.llm_providers / admin.llm_routes 等表），OCR（MinerU）在「外部服務」頁設定；兩者都不透過環境變數。

匯入進度、步驟時間軸與即時日誌可在「背景工作」頁查看。管理後台也用於瀏覽術語、管理外部 FHIR 伺服器、檢視 MCP 工具與備份設定；資料載入完成後可設 ADMIN_ENABLED=false 縮小公開部署的攻擊面，MCP 工具、worker 與排程匯入照常運作。詳見管理後台文件與背景工作與排程。

兩種介面都經由 nginx 前門提供（預設 :8080）：

/openapi.json 依「目前已啟用的工具」動態產生 OpenAPI 3.1 規格；每個工具對應 POST /tools/<工具名>，以 JSON body 當參數呼叫。客戶端只要填基底網址 http://<host>:8080，即會自動抓取 /openapi.json。

驗證：預設 PUBLIC_TOOLS_AUTH_MODE=none（不驗證，僅適合可信網路）。對外開放時設 PUBLIC_TOOLS_AUTH_MODE=bearer 與 PUBLIC_TOOLS_BEARER_TOKEN，三個端點（/mcp、/openapi.json、/tools/*）會一起要求 Authorization: Bearer <token>；PUBLIC_TOOLS_CORS_ORIGINS 在 bearer 模式下不可含 *。

audit | admin | icd | drug | health_supplements | food_nutrition | loinc | fhir（multi-IG）| snomed | rxnorm

完整定義見 db/schema.sql（PostgreSQL 容器首次啟動、資料卷為空時自動套用），增量變更見 db/migrations/。沒有 migration runner：既有資料庫須依檔名日期順序手動套用（例如 psql -U mcp -d taiwan_health -f db/migrations/20261020_loinc_structure.sql）。

# 後端（MCP + admin REST + worker）
cd node-server
npm install
npm run build          # tsc -> dist/
npm run typecheck      # tsc --noEmit
npm test               # node --test（node-server/src/**/*.test.ts）

# 管理後台 SPA（Vite）
cd web-v2
npm install
npm run dev            # http://localhost:5173/admin/，API 代理到 ADMIN_BACKEND（預設 http://127.0.0.1:8090）
npm run build          # tsc -b && vite build -> dist/
npm run typecheck

詳見開發指南與測試指南。

文件

完整文件請見 docs/，線上版由 MkDocs 發佈於 GitHub Pages（設定見 mkdocs.yml）。

致謝

• 台灣衛生福利部、TFDA

• Regenstrief Institute（LOINC）

• SNOMED International

• National Library of Medicine（RxNorm / UMLS）

• HL7 International（FHIR）

• WHO