Content
# Korea Health MCP Server
대한민국 공공 의료 데이터(data.go.kr)를 Claude 등 MCP 클라이언트에서 자연어로 조회하는 MCP 서버입니다. 로컬(stdio) 실행을 기본으로 하며, 원격(HTTP)으로 확장할 수 있도록 트랜스포트를 분리해 두었습니다.
> Status: **Implementation Complete · All 7 tools verified with actual keys** (2026-06-21). Type check 0 errors.
## Quick Start (npx · Recommended)
Clone and build are not required. Execute with **one command line** and issue a data.go.kr key.
Add to `claude_desktop_config.json`:
```jsonc
{
"mcpServers": {
"korea-health": {
"command": "npx",
"args": ["-y", "dk-korea-health-mcp"],
"env": {
"DATA_GO_KR_SERVICE_KEY": "issued_key",
"KEY_IS_ENCODED": "true"
}
}
}
}
```
> macOS config file path: `~/Library/Application Support/Claude/claude_desktop_config.json` — modify and restart Claude Desktop.
> `KEY_IS_ENCODED` is `"true"` for encoded keys and `"false"` for decoding keys.
## Provided Tools (10 exposed = 8 domain + 2 meta, 1 hidden)
| Tool | Description | Data Source |
|------|------|-------------|
| `kohealth_search_nonpayment` | Non-payment items, prices, and institutions by region and type (itemKeyword filter) | Health Insurance Review and Assessment Service (HIRA) non-payment medical fee information |
| `kohealth_get_hospital_nonpayment` | Non-payment list for a specific hospital (hospital name) | HIRA non-payment medical fee information |
| `kohealth_search_hospital` | Hospital search by institution name, region, type, and department (address, phone number, ykiho) | HIRA hospital information service |
| `kohealth_get_hospital_info` | Specialist numbers, medical equipment, and facilities by department for a hospital (ykiho) | HIRA medical institution detailed information service (v2.8) |
| `kohealth_get_clinic_top_diseases` | Top 5 diseases for clinics (clCd=31) by ykiho for the last year | HIRA hospital treatment information inquiry service |
| `kohealth_search_drug` | Search for drug efficacy, usage, precautions, and side effects | Ministry of Food and Drug Safety e-drug information |
| `kohealth_get_drug_dur` | DUR safety information (co-administration/age/pregnancy/ elderly/efficacy overlap) | Ministry of Food and Drug Safety DUR item information |
| `kohealth_get_disease_stats` | Disease name and code inquiry + statistics by gender, age, admission/outpatient, type, and region | HIRA disease information service |
| `discover_tools` / `execute_tool` | Hidden tools for discovery and proxy calls (meta tools) | — |
| _(hidden)_ `kohealth_get_drug_usage` | Drug usage (drug classification/ATC/ingredient × region/type/disease). Code required → call with `execute_tool` | HIRA drug usage information inquiry service |
## Pre-requisites (to be done manually)
1. Register on [data.go.kr](https://www.data.go.kr).
2. Apply for and obtain **"utilization application"** for each service (separate approval for each service, mostly automatic and free).
- [Health Insurance Review and Assessment Service (HIRA) non-payment medical fee information](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%88%EB%B3%B4%EC%9B%90%20%EB%B9%98%EA%B8%B8%EC%A7%84%EB%A3%8C%EB%B9%98%EC%A0%84%EB%A1%98%EB%A0%89%EB%B3%B4)
- [HIRA hospital information service](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%89%EC%90%90%20%EB%B9%98%EA%B8%B8%EC%A7%81%EB%B3%B4)
- [HIRA medical institution detailed information service](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%89%EC%90%90%20%EC%9D%98%EB%A3%8C%EA%B8%B8%EC%9C%A8%EB%B3%B4)
- [HIRA hospital treatment information inquiry service](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%89%EC%90%90%20%EB%B9%98%EA%B8%B8%EC%A7%81%EB%B3%B4)
- [HIRA disease information service](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%89%EC%90%90%20%EC%A7%88%EB%B3%B4%EC%A0%90%EB%A0%89%EB%B3%B4)
- [HIRA drug usage information inquiry service](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EB%B4%91%EA%B1%B4%EB%B3%B3%EC%88%98%EB%A0%89%EC%90%90%20%EC%9D%98%EB%A3%8C%EB%A0%89%EC%9C%A8%EB%B3%B4)
- [Ministry of Food and Drug Safety drug information (e-drug)](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EC%9D%98%EB%A3%8C%EB%93%B1%EB%A1%B1%EC%A0%84%20e%EB%A9%98%EB%9C%98%EC%98%88)
- [Ministry of Food and Drug Safety DUR item information](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=%EC%9D%98%EB%A3%8C%EB%93%B1%EB%A1%B1%EC%A0%84%20DUR%20%ED%92%88%EB%85%90%EC%A0%84)
3. Configure the issued service key — **(A) for npx usage**, add to Claude Desktop config `env` block (above *Quick Start*), **(B) for source build**, copy `.env.example` to `.env`.
```bash
cp .env.example .env
# DATA_GO_KR_SERVICE_KEY=issued_key
# KEY_IS_ENCODED=true # true for encoded keys, false for decoding keys
```
## Installation, Build, and Execution
```bash
npm install
npm run build
npm start # execute with stdio
npm run typecheck # tsc --noEmit
npm run inspect # test tools with MCP Inspector
```
## Connection to Claude Desktop (for source build)
> For npx usage, use the above *Quick Start*. Below is for source build.
Add to `claude_desktop_config.json` (keys are automatically loaded from `.env`, so no `env` needed):
```json
{
"mcpServers": {
"korea-health": {
"command": "node",
"args": ["/absolute/path/korea-health-mcp-server/dist/index.js"]
}
}
}
```
> macOS config file path: `~/Library/Application Support/Claude/claude_desktop_config.json`
> Restart Claude Desktop after modification.
## Verification Status (2026-06-21, actual keys)
All 7 domain tools verified live ✅ (examples with actual responses):
| Tool | Result | Live Example |
|------|------|------------|
| `kohealth_search_drug` | ✅ | "Goborinjeong" efficacy, usage, and side effects |
| `kohealth_search_hospital` | ✅ | "Seoul National University Hospital" (4 results: address, phone number, ykiho) |
| `kohealth_search_nonpayment` | ✅ | Seoul MRI → The Dream Hospital 690,000 KRW |
| `kohealth_get_hospital_nonpayment` | ✅ | Non-payment list for hospital name matching |
| `kohealth_get_drug_dur` | ✅ | Itraconazole ↔ Simvastatin / Rhabdomyolysis |
| `kohealth_get_hospital_info` | ✅ | Seoul National University Hospital internal medicine specialists 166, incubators 61 |
| `kohealth_get_clinic_top_diseases` | ✅ | Bumankiwon → keratitis, myopia, glaucoma, retinal disease, cataract |
| `kohealth_get_disease_stats` | ✅ | I10 (hypertension) by region: Seoul 1.36 million patients |
| `kohealth_get_drug_usage` (hidden) | ◐ | Endpoint verification, request variables and code |
## Remote (HTTP) Execution — Implemented
Run with `TRANSPORT=http` to start a stateless HTTP server.
```bash
TRANSPORT=http PORT=3000 npm start
# Health check
curl http://localhost:3000/healthz # {"ok":true}
# MCP call (initialize/tools/list/tools/call all POST /mcp)
curl -X POST http://localhost:3000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
Stateless structure for easy horizontal scaling.
## Structure
```
src/
index.ts # Bootstrap + transport selection (stdio/http) + handler wrapper
constants.ts # API base, service/operation, cache TTL, retry, pagination policy
types.ts # Common types (envelope, ToolDefinition, ToolContext)
services/
dataGoKr.ts # API client (key handling, URL construction, XML/JSON parsing, envelope normalization, cache)
fetchWithRetry.ts # Empty response, HTML check page, 5xx retry + exponential backoff
cache.ts # TTL cache (search 1h / detail 24h)
errors.ts # data.go.kr result code → actionable Korean messages
schemas/
common.ts # Common zod (pagination/format) + rendering/truncation helpers
normalizer/
searchNormalizer.ts # Natural language → validated parameters (PARAM_MAP) + region abbreviation normalization
tools/
nonpayment.ts hospital.ts clinicDiag.ts # Non-payment · hospital · clinic treatment
drug.ts dur.ts stats.ts drugUsage.ts # Drug · DUR · disease statistics · drug usage (hidden)
registry.ts # Tool registry (N implementations / few exposed)
metaTools.ts # discover_tools / execute_tool proxy
```
