Taiwan Health MCP Server
繁體中文 · English
台灣醫療健康資料整合 MCP 伺服器
整合 ICD-10-CM/PCS、SNOMED CT、LOINC、台灣 FDA 藥品 / 健康補充品 / 食品營養，以及 FHIR R4 IG 授權與驗證工具
https://github.com/user-attachments/assets/13527dd9-72ac-4e36-9868-7967399d4041
以官方 TypeScript MCP SDK（@modelcontextprotocol/sdk）建構的 Node.js 伺服器，對外提供 63 個工具，涵蓋 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 的客戶端，填入同一個網址即可。要在自己的環境部署，請看自行部署。
六大面向
|
FHIR Box 連接 · 3 個工具 管理者登錄院內 FHIR Box 或任何 FHIR R4 伺服器後，AI agent 就能查詢與讀取資源
|
TW IG 驗證與 grounding · 26 個工具 多 IG 剖面與 ValueSet、骨架填值產生資源、對齊 HL7
|
台灣藥品與營養 · 9 個工具 TFDA 藥品許可證、仿單 OCR、依刻字 / 顏色 / 外型辨識藥丸，加上健康食品與食品營養成分
|
|
國際語彙 · 13 個工具 ICD-10-CM / PCS（CMS 2026-04-01）、SNOMED CT International、LOINC 2.80 與 RxNorm：查碼、跨語彙映射、解讀檢驗值
|
臨床計算器 · 11 個工具 CHA₂DS₂-VASc、Wells、HAS-BLED、CURB-65、qSOFA、GCS、eGFR、DAS28、CDAI、BMI（台灣切點）；確定性計算，不讓 LLM 自己算
|
語意搜尋 · 跨模組 ICD-10、LOINC、SNOMED CT 與 IG CodeSystem 以 pgvector 嵌入（預設 Ollama
|
全部 63 個工具
| 群組 | 工具 |
|---|---|
| ICD-10 | search_medical_codes、infer_complications、get_nearby_codes、check_medical_conflict、browse_icd_category |
| 藥品 / TFDA | search_drug、identify_unknown_pill、get_drug_details、get_drug_asset_links |
| 檢驗 / LOINC | search_loinc、query_loinc、interpret_lab_result、batch_interpret_lab_results |
| SNOMED CT | search_snomed_concept、query_snomed_concept、get_snomed_relationships、query_snomed_mapping |
| FHIR Condition | query_fhir_condition、validate_fhir_condition |
| FHIR Medication | query_fhir_medication、validate_fhir_medication |
| FHIR IG（授權 / 驗證） | fhir_list_igs、fhir_get_ig、fhir_list_artifacts、fhir_search_artifacts、fhir_list_resource_profiles、fhir_rank_resource_profiles、fhir_get_profile、fhir_get_profile_elements、fhir_get_profile_required_elements、fhir_get_valueset、fhir_expand_valueset、fhir_lookup_code、fhir_validate_code、fhir_normalize_code、fhir_resolve_reference、fhir_build_bundle、fhir_validate_resource、fhir_validate_bundle、fhir_get_resource_skeleton、fhir_finalize_resource、fhir_check_grounding、fhir_check_completeness |
| 健康補充品 | search_health_supplements |
| 食品營養 | query_food_nutrition、query_food_ingredient、search_foods_by_nutrient、analyze_meal_nutrition |
| FHIR 伺服器 | list_fhir_servers、get_fhir_server_status、 |
架構
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.jsweb/只留在 compose profilelegacy-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 登入管理後台匯入資料。完整說明見部署指南。
啟動的服務與重新部署
| 服務 | 說明 |
|---|---|
nginx | 單一對外入口，預設 :8080（WEB_PORT） |
web-v2 | 管理後台 SPA（Vite 靜態檔，由容器內 nginx 提供）；前門把 /admin 與其餘頁面導到這裡 |
app | Node MCP 伺服器 + 管理後台 REST API（node dist/server.js；只在內部網路，不對主機開埠） |
admin-worker | 背景工作執行器（所有匯入與嵌入工作，node dist/admin/adminWorker.js） |
postgres | PostgreSQL 16 + pgvector |
pgbouncer | 連線池（transaction mode） |
redis | 管理後台即時事件的 pub/sub 轉送與健康檢查；目前沒有任何工具回應被快取 |
minio + minio-init | 物件儲存（管理後台上傳的來源檔、藥品資產） |
舊的 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 容器）。
-
管理後台預設啟用（
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登入。 -
在各模組頁（側邊欄「醫療術語」、「藥品」、「健康食品」、「食品營養」、「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 分析）、健康補充品、食品營養。
- 需上傳來源檔（上傳後按匯入）：ICD-10-CM（CMS order file zip）/ ICD-10-PCS、WHO ICD-10（選用）、LOINC、SNOMED CT、RxNorm；FHIR IG 可由套件 registry 安裝或上傳
-
嵌入（語意搜尋）為獨立的
*_embed工作，可於各模組頁面執行。嵌入與分析 LLM 的端點在「模型端點」頁設定（provider 帳號 + 路由，存於admin.llm_providers/admin.llm_routes等表），OCR（MinerU）在「外部服務」頁設定；兩者都不透過環境變數。
匯入進度、步驟時間軸與即時日誌可在「背景工作」頁查看。管理後台也用於瀏覽術語、管理外部 FHIR 伺服器、檢視 MCP 工具與備份設定；資料載入完成後可設 ADMIN_ENABLED=false 縮小公開部署的攻擊面，MCP 工具、worker 與排程匯入照常運作。詳見管理後台文件與背景工作與排程。
連接客戶端與驗證
兩種介面都經由 nginx 前門提供（預設 :8080）：
| 介面 | 端點 | 適用客戶端 |
|---|---|---|
| MCP（streamable-http） | http://<host>:8080/mcp | 原生 MCP 客戶端（Claude Desktop、Open WebUI v0.6.31+ 的 MCP 連線等） |
| OpenAPI bridge | GET http://<host>:8080/openapi.json、POST http://<host>:8080/tools/<工具名> | 僅支援 OpenAPI 工具伺服器的客戶端（如 Open WebUI 的 External Tools / OpenAPI 類型） |
/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 模式下不可含*。
資料庫 Schema
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