Taiwan Health MCP Server

🇹🇼 台灣醫療健康資料整合 MCP 伺服器 整合 ICD-10-CM、SNOMED CT、RxNorm、LOINC、FDA 藥品/保健食品/營養、TWCore IG、臨床指引，支援 FHIR R4 標準

---

✨ 專案特色

• 🇹🇼 台灣在地化 — 整合台灣 FDA、衛福部官方開放資料，支援繁體中文
• 🔗 國際標準 — 符合 FHIR R4、ICD-10-CM 2025、LOINC 2.80、SNOMED CT、RxNorm、ATC
• 🏥 28 個 MCP 工具 — 由動態 registry 管理，涵蓋診斷、藥品、檢驗、指引、術語；RxNorm 能力已併入 search_drug modes
• 🏗️ 生產就緒 — PostgreSQL 16 + pgBouncer + Redis + Prometheus，支援每秒數百請求
• 🔄 自動同步 — FDA 藥品/保健食品/營養資料每週自動更新

---

🚀 快速開始

前置需求

• Docker + Docker Compose
• 至少 4 GB 可用記憶體

1. 準備環境

git clone https://github.com/healthymind-tech/Taiwan-Health-MCP.git
cd Taiwan-Health-MCP
cp .env.example .env
cp config/datasets.example.yaml config/datasets.yaml
# 編輯 .env，至少設定 POSTGRES_PASSWORD
# 視部署環境編輯 config/datasets.yaml，指定各 dataset 的實際檔案位置

2. 啟動服務

docker compose up -d

這會啟動四個容器：postgres、pgbouncer、redis、app（MCP server）。

3. 載入術語資料

術語資料（ICD、LOINC、SNOMED CT 等）需手動下載後，在 config/datasets.yaml 設定檔案位置，再執行 loader：

# 全部載入（建議首次部署）
docker compose --profile loader run --rm data-loader --all

# 僅初始化 FDA 動態資料
# 注意：Drug 匯入採 RxNorm-first 防呆，未先載入 RxNorm 會阻擋 --drug/--fda
docker compose --profile loader run --rm data-loader --rxnorm
docker compose --profile loader run --rm data-loader --fda
docker compose --profile loader run --rm data-loader --drug
docker compose --profile loader run --rm data-loader --health-food
docker compose --profile loader run --rm data-loader --food-nutrition

# 或依需求單項載入
docker compose --profile loader run --rm data-loader --icd        # ICD-10-CM 2025
docker compose --profile loader run --rm data-loader --loinc      # LOINC 2.80
docker compose --profile loader run --rm data-loader --twcore     # TWCore IG
docker compose --profile loader run --rm data-loader --guideline  # 臨床指引
docker compose --profile loader run --rm data-loader --snomed     # SNOMED CT（5-15 分鐘）
docker compose --profile loader run --rm data-loader --rxnorm     # RxNorm

DATASETS_CONFIG 預設為 /app/config/datasets.yaml。若未設定，loader 會回退到舊的 /app/fhir-code 目錄規則。新部署建議使用 config/datasets.yaml，避免依賴固定檔名與固定目錄結構。

--all 現在也會初始化 Taiwan FDA 藥品、健康補充品、營養資料，且會自動處理相依順序（包含先載入 RxNorm）。 app 仍會在首次啟動或資料過期時自動同步；若想在部署階段先灌資料，建議使用 data-loader --all，或手動依序執行 --rxnorm 後再 --fda。

4. 確認服務正常

# 查看服務狀態
docker compose ps

# 健康檢查（需先建立 MCP session）
curl http://localhost:8000/mcp -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

升級既有資料庫（無資料遺失遷移）

若您的環境是在 RxNorm 併入 drug schema 之前建立，請先執行一次 migration：

# 1. RxNorm 整併與 drug schema 補強
docker compose exec -T postgres psql \
  -U ${POSTGRES_USER:-mcp} \
  -d ${POSTGRES_DB:-taiwan_health} \
  -v ON_ERROR_STOP=1 \
  < db/migrations/2026-04-12_drug_schema_no_loss.sql

# 2. 移除已棄用的 embedding 資料表（drug.license_embeddings, drug.atc_embeddings）
docker compose exec -T postgres psql \
  -U ${POSTGRES_USER:-mcp} \
  -d ${POSTGRES_DB:-taiwan_health} \
  -v ON_ERROR_STOP=1 \
  < db/migrations/2026-04-12_drop_unused_drug_embeddings.sql

migration 1 會把不符合新約束的舊資料先備份到 migration_backup.*，再進行去重與約束補強。migration 2 移除從未被查詢的 embedding 資料表。

5. 連接 Claude Desktop

在 claude_desktop_config.json 加入：

{
  "mcpServers": {
    "taiwan-health": {
      "url": "http://localhost:8000/mcp",
      "transport": "streamable-http"
    }
  }
}

---

🏗️ 基礎架構

元件	版本	用途
PostgreSQL	16-alpine	主要資料庫（所有術語資料）
pgBouncer	edoburu/latest	連線池（transaction mode，500 client → 30 PG 連線）
Redis	7-alpine	回應快取（TTL 策略，@cached 裝飾器）
Prometheus	—	指標監控（預設 port 9090）
mcp SDK	1.25	官方 MCP SDK（mcp.server.fastmcp.FastMCP）
asyncpg	—	高效能 PostgreSQL 非同步驅動

PostgreSQL Schema

audit | icd | drug | health_food | food_nutrition | loinc | guideline | twcore | snomed

drug schema 內包含 FDA 藥品資料與 RxNorm 子表（rx_concepts / rx_relationships / rx_atc_map）。

---

📋 核心功能（28 個 MCP 工具）

工具分類、status page 範例與 dataset gating 由同一份 registry 產生；tools/list 只會顯示已載入資料集對應的工具，health_check 永遠可用。FHIR、TWCore 與臨床指引已合併成較少的對外入口。

群組	工具數	功能
系統	1	health_check：資料庫、快取、資料集狀態一覽（永遠可用）
ICD-10	5	診斷碼搜尋、併發症推論、鄰近碼、衝突檢查、分類瀏覽
藥品	2	search_drug（名稱 / ATC / 成分 / 許可證 / RxNorm 解析 / RXCUI 成分 / 交互作用）與外觀辨識
健康補充品	1	search_health_supplement：關鍵字、許可證、疾病情境推薦
食品與營養	4	query_food_nutrition（營養查詢 + 詳細面板）、query_food_ingredient（原料合規）、search_foods_by_nutrient（營養排序）、analyze_meal_nutrition（餐點分析）
FHIR Condition	2	ICD-10 / 關鍵字 → FHIR R4 Condition，驗證
FHIR Medication	2	藥品 / 關鍵字 → FHIR R4 Medication / MedicationKnowledge
LOINC / Lab	4	search_loinc / query_loinc 入口 + 單項/批次判讀
臨床指引	2	指引搜尋、分段內容、臨床路徑
TWCore IG	1	台灣核心 CodeSystem 統一查詢入口
SNOMED CT	4	概念搜尋、階層查詢、關聯查詢、ICD-10 雙向對應

---

📦 資料集

資料集	版本	授權	說明
ICD-10-CM	2025 (NLM)	公開	診斷碼
ICD-10-PCS	2025 (CMS)	公開	手術/處置碼（78,948 筆，--icd 同時載入）
LOINC	2.80	LOINC License	87,000+ 檢驗碼
SNOMED CT International	20250601	SNOMED License	370,000+ 臨床概念、IS-A 階層
RxNorm	2024-06-03	公開 (NLM)	藥品命名、藥物交互作用
TWCore IG	v1.0.0	公開 (MOHW)	30+ 台灣健保 CodeSystem
Taiwan FDA 藥品	每週更新	公開 (FDA)	66,000+ 藥品許可證
Taiwan FDA 健康補充品	每週更新	公開 (FDA)	核可健康補充品
Taiwan FDA 營養	每週更新	公開 (FDA)	食品營養成分資料庫
臨床指引	自整理	—	台灣醫學會指引（種子資料）

---

⚠️ 重要限制

• 健康補充品疾病對應 — 開發者整理，未經醫學驗證，不適合直接面向患者
• FHIR 驗證 — 僅檢查必要欄位；生產環境請使用 HL7 FHIR Validator
• ICD-10-PCS — 已內建 2025 版（78,948 筆），--icd 自動同時載入 CM 和 PCS；icd.procedures 未載入時工具自動降級
• SNOMED CT — 需有效的 SNOMED International 授權（多數用途免費）
• 藥物交互作用 — RxNorm interacts_with 不含嚴重程度評級，須由臨床醫師確認
• pgBouncer transaction mode — 不相容於 LISTEN/NOTIFY 和 named prepared statements（asyncpg 已設 statement_cache_size=0）

---

🤝 貢獻

歡迎貢獻！詳見 CONTRIBUTING.md。

主要需求：

• 補充/驗證臨床指引種子資料
• 新增 LOINC 中文對照
• 補充健康補充品疾病對應（需醫學審核）
• 補充/驗證臨床指引種子資料

---

📞 聯絡

• GitHub Issues: 回報問題
• Email: [email protected]

---

👥 Contributors

Made with contrib.rocks.

---

🙏 致謝

• 台灣衛生福利部、TFDA（ICD、藥品、健康補充品、營養資料）
• Regenstrief Institute（LOINC）
• SNOMED International（SNOMED CT）
• National Library of Medicine（RxNorm、ICD-10-CM）
• HL7 International（FHIR）
• WHO（ICD、ATC）
• Twinkle AI — 感謝社群串接本專案打造 Twinkle Health Agent

⭐ 如果這個專案對您有幫助，請給我們一個 Star！

⭐ Star History