内容
韩国健康MCP服务器
대한민국 공공 의료 데이터(data.go.kr)를 Claude 등 MCP 클라이언트에서 자연어로 조회하는 MCP 서버입니다. 로컬(stdio) 실행을 기본, 원격(HTTP)으로 확장할 수 있도록 트랜스포트를 분리해 두었습니다.
> **实现完成 · 7个工具全部使用实际密钥进行在线验证**(2026-06-21). 类型检查 .
## 快速开始 (npx · 推荐)
·编译无需执行，只需**一行命令**即可运行。 data.go.kr 密钥 발급(见下文 * 사전 준비 *)即可。
在 `claude_config.json` 中添加jsonc
{
"mcpServers": {
"korea-health": {
"command": "npx",
" ["-y",-korea-health-mcp"],
"env": {
_GO_KR_SERVICE_KEY": " 발급받은_키",
"KEY_IS_ENCODED": "true"
}
}
}
}
```
> mac路径：`~/Library/Claude/claude_config.json` — 修改后关闭 Claude Desktop 并。
> `KEY_IS_ENCODED` 为一般认证Encoding）则为 `" Decoding 密钥则false"`。
>从源码编译，请参考下文 *安装 · 编译 · 运行*。
## 提供工具（ 노출 10 = 领域 + 元数据 2，隐藏 1）
| 工具 | 描述 | 数据来源 |
|------|------|-------------|
|health_search_nonpayment`地区/类别 非付费项目·价格·机构（ 过滤） | 医保局 非付费医疗费用信息 |
| `kohealth_get_hospital_nonpayment` | 特定医院（医院名称）的非付费列表 | 医保局 非付费医疗费用信息 |
| `kohealth_search_hospital` | 机构名称/地区/类别/科室搜索医院（地址·电话·ykiho） | 医保局 医院信息服务 `kohealth_get_info` | 通过 ykiho 查询科室专业医生数量·医疗设备·设施 | 医保局 医疗机构详细信息服务（v2.8） |
| `kohealth_get_clinic_top_diseases` | 诊所（clCd=31）ykiho 最近 1 年 前 5 个 医保局 医院诊疗信息查询服务 |
| `kohealth_search_drug` | 药品功效·注意事项·副作用搜索 | 食药局 e약은| `kohealth_get_dur` | DUR 安全信息（联合用药/年龄/孕妇/老人/功效重复） | 食药局信息 |
| `kohealth_get_disease_stats` |病名称·代码查询 + 性别年龄/住院门类别/地区医疗统计 | 医保局 疾病信息服务 |
| `dis` / `execute_tool` | 隐藏工具发现调用（扩展元工具） |
| _(隐藏)_ `kohealth_get_drug_usage` | 付费药品使用量（药效分类/成分 × 地区/疾病）。需要代码 → `execute_tool` 调用医保局 药品使用服务 |
> 连接线索付费搜索和医院返回医院名称·ykiho。 `kohealth_search_hospital` 的 ykiho 可以传递给 `kohealth_get_hospital_info`，继续医院的科室·设备。 （ykiho 在列表不能作为*输入过滤器*，因此医院搜索仅医院名称）
单位的 청구明细不提供公开 API。可以获取的是公开药品信息和汇总统计。
## 사전 준비 (需要自行1. [data.go.kr](https://www.data) 注册会员
2. 以下各服务中 **"활용신청"** （每个服务单独审批，大部分自动审批·免费）。如果链接打在 data.go.kr 搜索框中输入相同的名称：
健康保险审查_非付费医疗](https://www.data/tcs/dss/selectDataSetList.do?dType=API&keyword=健康保险审查评估院%20非付费医疗费用信息)
- [健康保险审查评估院_医院信息服务](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=健康保险审查评估院%20医院信息服务)
- [健康保险审查_医疗机构详细信息服务](https://www.data.go.kr/dss/selectData.do?dType=API&keyword=健康保险审查评估院%20医疗机构)
- [健康保险审查评估院_医院诊疗信息查询服务](https://www.data.go.kr/tcs/selectDataSetListdType=API&健康保险审查评估院%20医院诊疗信息查询服务)
- [健康保险审查评估院_疾病信息服务](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=健康保险审查评估院%20疾病)
- [审查评估院_药品查询服务](https://www.data.go.kr/tcs/dss/selectDataSetList.do?dType=API&keyword=健康保险审查评估院%20药品使用信息查询服务)
- [食品药品安全处_药品概要信息（e약은요）](www.data.go.kr/tss/selectDataSet?dType=API=药品概要信息%20e약은요)
- [食品药品安全处_药品安全使用服务（DUR）项目信息](https://www.data.go.kr/tcs/selectDataSetList.do?dType=API&keyword=药品%20DUR%20项目信息)
3. 配置 발급的服务密钥 — **（A）使用 npx 时** 在 Claude Desktop `env` 块中（上文 *快速开始*），**（B）源码编译时** 在 `. 中（复制 `.env.example。
```bash .env.example .env
# DATA_GO_KR_SERVICE_KEY= 발급받은_키
# KEY_IS_ENCODE # Encoding 密钥，Decoding false（密钥为 hex 则无关）
```
> `. 在执行位置（cwd）无关的情况下**从项目根目录自动加载**。因此，不需要在 Claude Desktop 配置中重复设置密钥。
## 安装 · 编译 · 运行
```bash
npm install
npm run build
npm start # stdio 运行
npm run typecheck # tsc --noEmit
npm run inspect # MCP Inspector 测试工具
```
## 连接 Claude Desktop（源码编译时）
> 使用 npx 时请参考上文 *快速开始*。以下是在源码编译后的情况。
在 `claude_desktop_config.json` 中添加（密钥由 `.env` 自动加载，因此不需要 `env`）:
```json
{
"mcpServers": {
"korea-health": {
" "node",
"args": ["/绝对路径/korea-health-mcp-server/dist/index.js"]
}
```
> macOS 配置文件路径：`~/Library/Application Support/Claude/claude_desktop_config.json`
> 修改后请完全关闭 Claude Desktop 并重新启动。
## 在线验证现状（20206-21，实际密钥）
7 个领域工具全部在线验证 ✅ （示例为实际响应）：
| 工具 | 结果 | 在线示例 |
|------|------|------------|
| `kohealth_search_drug` | ✅ | "게보린정" 功效·用法·副作用 |
kohealth_search_hospital` | ✅ | "서울대학교병원" 4 项·电话·ykiho| `ko_nonpayment` | ✅ | 首尔 MRI → 더드림医院 69 万韩元 |
| `kohealth_get_hospital_nonpayment` | ✅ | 医院名称匹配非付费列表 |
| `kohealth_get_drug_dur` | ✅ | 이트라코나졸 ↔ 심바스타틴 / 횡문근융해증 |
| `kohealth_get_hospital_info` | ✅ | 首尔大学医院 内科专业医生 166 人 / 婴儿培养箱 61 台 |
| `kohealth_get_cl_diseases` | ✅ | 봄안과의원 →炎·近青光眼·膜疾病·白内| `kohealthisease_stats` | ✅ |（高血压）地区分布：首尔患者 136 万人 |
health_get_drug_usage` （隐藏） | | 端点验证变量·代码需要使用指南 |
> 本地（stdio）·远程（HTTP均已启动并tools/list`。
已在线确定并反映在代码中的事项：
- **端点版本·后缀**: 医疗机构详细信息 `MadmDtlInfoService2.8`（非 2.7），疾病信息 `diseaseInfoService1`（后缀 1）。最初两个均为 Forbidden/error，但并非审批问题，而是路径问题。
- **sidoCd 是数字代码** （首尔 110000， 全罗南道 ， 세종 ）。 `SIDO 映射 + `normalizeRegion()` 将 "首尔" 转换为 "110000"。
- **服务器过滤不生效的项目** （非付名称·医院名称， DUR 成分名称，）通过 `()` 处理。疾病（2065 项）一次性获取（缓存）并过滤。ykiho 在列表搜索中不能作为输入过滤器基于医院名称。
疾病统计必须 `year`**，与 `sickCd` 一起。 4 种（性别年龄/住院门诊/类别/地区）具有相同的参数 **XML 响应字段名称**：e약은Case（efcyQesitm…），D写下划线（, PROH, MIXTURE_*/医院详细信息各不相同 — 已反映在中。
- **器错误修复**：TagValue:false` （否则 `<resultCode>resultCode>` 被数字 0，导致正常响应被错误处理）。
剩余的选题：
- 新增审批服务（药品使用信息查询服务，医院诊疗信息查询服务）对应的工具 — 如有需要，在/` 中逐一- HTTP 远程部署runHttp()`）。
## 远程（HTTP）执行 — 已实现TRANSPORT=http`able HTTP（无服务器。工具代码与 100% ```bash
TRAN PORT=3000 npm start
# 健康检查 http://localhost:/healthz # {"ok":true}
# MCP 调用（initialize/tools/list/tools/call 均为 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":{}}'
```
每个请求都创建新的服务器和传输，因此有利于水平扩展（如果需要会话保持，请指定 `sessionIdGenerator`）。
## 结构
```
src/
index.ts # 引导 + 传输选择（stdio/http）+ 处理器包装
constants.ts # API 基础，服务/操作，缓存 TTL·重试·分页策略
types.ts # 公共类型（Envelope, ToolDefinition, ToolContext）
services/
dataGoKr.ts # API 客户端（密钥处理，URL 拼接，XML/JSON 解析，Envelope 标准化，缓存）
fetchWithRetry.ts # 空响应·HTML 检查页面·5xx 重试 + 指数级回退
cache.ts # TTL 缓存（搜索 1h / 详情 24h）
errors.ts # data.go.kr 结果 可行动的中文 schemas/
common.ts # 公共 zod（分页/格式）+ 渲染/截断帮助函数
normalizer/
searchNormalizer.ts # 自然语言 → 验证参数（PARAM_MAP）+ 地区简称标准化
tools/
nonpayment.ts hospital.ts clinicDiag.ts # 非付费 · 医院 · 诊所诊疗
drug.ts dur.ts stats.ts drugUsage.ts # 药品 · DUR · 疾病统计 · 药品使用（隐藏）
registry.ts # 工具注册表（实现 N 个 / 暴露少数）
metaTools.ts # discover_tools / execute_tool 代理
```
- `index.ts` 的 `runHttp()` 实现 Streamable HTTP 传输（无状态）。 `.env` 在项目根。
### 设计笔记
从 k-mcp 生态系统调查中提取了 模式。
1.责任分离** — /解析/`dataGoKr.ts`）↔ 重试（`fetchWithRetry.ts`）↔ 缓存（`cache.ts`。
2. **参数修正层** — `searchNormalizer.ts` 将自然语言/逻辑键转换为验证的 API 参数。未确定的参数名称在 `PARAM_MAP` 中收集并 进行管理。
3. **实现 N 个 / 暴露少数** — `registry` + `metaTools(discover_tools→execute_tool)` 结构，即使工具增加，也能保持 ListTools 上下文较小。
