MCP Taiwan NHI IHQE

MCP Taiwan NHI IHQE wraps Taiwan National Health Insurance Administration's public Healthcare Quality Information Disclosure website:

https://med.nhi.gov.tw/ihqe0000/

The project fetches the public indicator index, parses metric metadata, looks up area codes, and queries hospital-level indicator values. It exposes those flows as a FastMCP server so an MCP client can search available quality metrics and query metric values without manually browsing the website.

Traditional Chinese documentation is available in README.zh-tw.md.

Provided Tools

list_metric

List available quality metrics parsed from the IHQE public index.

Arguments:

• keyword: Optional keyword to search by metric id, metric name, or section.
• limit: Optional maximum number of metrics to return.

Returns:

• metrics: Matching metric records.
• total: Total number of matched records.
• returned: Number of records returned after applying limit.

query_metric

Query hospital values for one quality metric.

Arguments:

• metric: Metric id or metric name keyword, for example 1711 or 血脂.
• year: ROC year/quarter string, for example 114Q4.
• roc_year: ROC or Gregorian year. Use with quarter when year is omitted.
• quarter: Quarter value such as 4 or Q4. Use with roc_year.
• city: City/town code or area name, for example 12, 1205, 新竹市, or 香山.
• hospital_name: Optional hospital name keyword.
• hospital_id: Optional hospital id.
• special: Optional special type code.
• branch: Optional NHI branch code.
• limit: Maximum number of rows to return. Default is 20.

Returns:

• metric: The resolved metric metadata.
• city: The resolved city/town code used in the API call.
• rows: Hospital-level metric rows.
• total: Total number of matched rows.
• returned: Number of rows returned after applying limit.

describe_metric

Return the indicator introduction and description for one quality metric.

Arguments:

• metric: Metric id or metric name keyword, for example 1711 or 血脂.

Returns:

• metric: The resolved metric metadata.
• title: The indicator page title.
• introduction: Structured introduction sections (each with title and content).

health_education

Return the health education content for one quality metric.

Arguments:

• metric: Metric id or metric name keyword.

Returns:

• metric: The resolved metric metadata.
• title: The indicator page title.
• health_education: Structured health education sections (each with title and content).

Usage

Install Dependencies

uv sync

Run as an MCP Server

This repository includes a local MCP configuration:

{
  "mcpServers": {
    "tw-nhi-ihqe": {
      "command": "uv",
      "args": ["run", "ihqe-mcp"]
    }
  }
}

You can also run the server directly:

uv run ihqe-mcp

The IHQE website currently fails Python's default certificate validation in some environments, so SSL verification is disabled by default for the MCP server. To force verification, set:

IHQE_VERIFY_SSL=true uv run ihqe-mcp

Try the CLI

List available metrics:

uv run ihqe list-metrics
uv run ihqe list-metrics --keyword 血脂

Look up area codes:

uv run ihqe list-areas
uv run ihqe list-areas --keyword 香山
uv run ihqe list-areas --towns

Query a metric:

uv run ihqe query-metric 1711 --year 114Q4 --city 12 --limit 5
uv run ihqe query-metric 1711 --year 114Q4 --city 香山 --keyword 台大 --limit 5

Use JSON output when inspecting raw data:

uv run ihqe query-metric 1711 --year 114Q4 --city 12 --json

Describe an indicator (introduction and methodology):

uv run ihqe describe-metric 1711
uv run ihqe describe-metric 血脂

Show health education content for an indicator:

uv run ihqe health-education 1711
uv run ihqe health-education 血脂 --json

Development

Project Layout

• src/mcp_tw_nhi_ihqe/parser.py: HTML parsers for the public index and metric content pages.
• src/mcp_tw_nhi_ihqe/api.py: Low-level API client and higher-level cached IHQE client.
• src/mcp_tw_nhi_ihqe/cli.py: Command-line workflow for local testing.
• src/mcp_tw_nhi_ihqe/mcp.py: FastMCP server and tool definitions.
• tests/: Unit tests and fixed HTML fixtures.

Run Tests

uv run pytest

Useful Local Checks

uv run ihqe list-metrics --keyword 血脂
uv run ihqe list-areas --keyword 香山
uv run ihqe query-metric 1711 --year 114Q4 --city 12 --limit 2

Notes for Contributors

• Keep network-dependent behavior behind injectable clients or fixed fixtures.
• Prefer adding tests with small HTML/API samples before changing parser logic.
• The official API uses ROC year/quarter values such as 114Q4.
• The official API accepts either city codes such as 12 or town/district codes such as 1205 in the same city query parameter.