healthcare-opendata-mcp 🏥

官方開放資料 → 可查詢 MCP 介面，讓 AI agent 不必直接處理分散的政府資料來源。

Self-hosted MCP server that syncs Taiwan government procurement (PCC) and National Health Insurance (NHI) open data into a local SQLite database, then exposes it through read-only MCP tools. A SELECT-only query guard (syntax allowlist plus a read-only SQLite authorizer) keeps the Twinkle-compatible query_rows interface safe for agent-driven querying.

healthcare-opendata-mcp（命令名稱：hcmcp）是一個自建、可部署的 MCP server：把政府電子採購網與健保署開放資料同步到 SQLite，再以穩定的 MCP tools 提供給 Claude 或其他 agent 查詢。

專案保留 Twinkle Hub query_rows 的 SQL 式查詢模式，但資料來源、同步流程與儲存層都由本專案自行掌握，不依賴第三方聚合服務。

GitHub Pages 導覽 · GitHub repository

Contents

• Why

• How it works

• Install

• What it provides

• Querying

• Trust & security

• HTTP & GKE

• Development

• Scope & limits

• Related projects

• License

Related MCP server: M3

Why

AI agent 要查政府資料時，真正的摩擦通常不在模型，而在資料入口：來源分散、格式不同、欄位缺漏，而且外部聚合服務的政策或可用性可能改變。

How it works

flowchart LR
    PCC[政府電子採購網<br/>半月 XML] --> SYNC[hcmcp-sync<br/>fetch / normalize / upsert]
    NHI[健保署開放平台<br/>CSV API] --> SYNC
    SYNC --> DB[(SQLite<br/>~/.hcmcp/hcmcp.db)]
    DB --> SERVER[hcmcp<br/>唯讀 MCP server]
    SERVER --> AGENT[Claude / Agent]
    AGENT -->|按需補查| DETAIL[get_tender_detail]
    DETAIL --> PCCDETAIL[政府採購網<br/>標案明細頁]

The project keeps ingestion and querying separate:

1. hcmcp-sync pulls official sources and writes the shared SQLite database.

2. hcmcp opens the same database in the query path and exposes MCP tools.

3. list_datasets → get_dataset → query_rows is the recommended discovery flow.

4. get_tender_detail performs an on-demand lookup when a tender needs deadline, opening time, or budget details.

Install

git clone https://github.com/trionnemesis/healthcare-opendata-mcp.git
cd healthcare-opendata-mcp

python3.11 -m venv .venv
.venv/bin/python -m pip install -e .

# 建立或更新預設 DB：~/.hcmcp/hcmcp.db
.venv/bin/hcmcp-sync

加入 Claude Code：

claude mcp add hcmcp -- /absolute/path/to/healthcare-opendata-mcp/.venv/bin/hcmcp

Database path

hcmcp-sync 與 hcmcp server 共用同一個預設 DB：~/.hcmcp/hcmcp.db。如果要改路徑，兩個 process 都必須使用相同的 HCMCP_DB；sync 也可以使用 --db：

HCMCP_DB=/path/to/hcmcp.db .venv/bin/hcmcp-sync
HCMCP_DB=/path/to/hcmcp.db .venv/bin/hcmcp

否則可能出現「同步成功，但 server 查不到資料」的路徑漂移問題。

What it provides

Datasets

目前 CLI 預設同步兩個資料集：

MCP tools

Querying

先看資料集與 schema，再執行查詢：

list_datasets()
get_dataset(dataset_id="pcc-tender", sample_rows=5)

query_rows 保留 Twinkle 相容的 SQL-style 查詢介面，支援欄位選取、WHERE、GROUP BY、排序與聚合：

query_rows(
    dataset_id="pcc-tender",
    columns=[
        "agency",
        "COUNT(*) AS n",
        "SUM(CAST(award_price AS INTEGER)) AS total",
    ],
    where="announcement_type='決標公告' AND date >= '2025-01-01'",
    group_by=["agency"],
    order_by="total DESC",
    limit=50,
)

SQLite 使用 LIKE，不使用 PostgreSQL 的 ILIKE；金額欄位需要依資料內容使用 CAST(... AS INTEGER)。

Trust & security

query_rows 接受 SQL 片段，因此實作了兩層防禦：

• 語法層：只允許單一 SELECT；拒絕多語句、註解、PRAGMA、ATTACH、DML、DDL 與危險 keyword，並將 limit 硬上限設為 400。

• 執行層：使用 SQLite read-only connection 與 authorizer allowlist，只允許讀取單一物化資料表；另有 VM 步數上限。

這是查詢執行安全邊界，不是使用者認證層。MCP server 本身沒有 authentication；HTTP/GKE 部署應放在內部網路，或在前方配置 IAP、service mesh mTLS 等存取控制。

HTTP & GKE

本機或容器可使用 MCP streamable HTTP：

HCMCP_TRANSPORT=http HCMCP_PORT=8000 .venv/bin/hcmcp

curl http://localhost:8000/healthz
# {"status":"ok"}

claude mcp add --transport http hcmcp http://<host>:8000/mcp

HCMCP_TRANSPORT=sse 僅保留給既有部署相容；新網路部署使用 http。GKE 架構、Workload Identity、CronJob、GCS DB artifact 與 Kubernetes manifests 請見 deploy/README.md。

Development

.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest

主要程式分層如下：

src/health_opendata_mcp/
├── adapters/      官方來源 adapter 與 HTTP/CSV/PCC parser
├── domain/        query_guard 等純函式安全規則
├── ingestion/     discover → fetch → normalize → upsert pipeline
├── repository/    SQLite schema、物化表與唯讀 query executor
└── mcp_server/    FastMCP tools、transport 與 QueryService

新增健保資料集只需在 cli.py 的 NHI_DATASETS 登錄 rId；新增資料來源則實作 SourceAdapter 的 discover、fetch、normalize。

Scope & limits

• 預設同步範圍刻意收斂為衛福部資訊勞務相關標案與健保診所，不是完整的政府採購或醫療資料目錄。

• get_tender_detail 依賴政府電子採購網即時明細頁；舊案下架、網站維護或限流時，工具可能回傳錯誤，應稍後重試。

• HTTP server 預設沒有 authentication；公開暴露前必須自行配置網路層存取控制。

• 資料依官方來源更新節奏而變動；本 repo 不把同步後的資料快照提交進 Git。

Related projects

g0VMCP — 衛福部標案的生命週期與明細加值 MCP，處理招標 → 更正 → 決標狀態與深度標案情報。兩個專案刻意零耦合：本專案提供 Twinkle 相容的扁平列查詢，g0VMCP 提供深度標案資訊；PCC XML parser 以純函式方式 vendored 自 g0VMCP。

opendataCampus-MCP — 教育資源導航 MCP，以 TWCampus 為目錄入口路由至台灣官方教育平台。與本專案同屬「官方開放資料 → 可查詢 MCP 介面」系列，但服務網域為教育資源而非採購／健保。

License

MIT — 資料依政府資料開放授權條款使用。