mcp-tw-nhi-ihqe 0.1.0

MCP server for Taiwan NHI IHQE healthcare quality indicators

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.