Skip to main content
Glama
README.md
# korean-onlabel-mcp

식약처 허가 원문으로 의약품·의료기기 광고 문구가 허가 범위 안인지 검증하는 MCP 서버입니다.

[![CI](https://github.com/itso-wavy/korean-onlabel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/itso-wavy/korean-onlabel-mcp/actions/workflows/ci.yml)

![광고 문구 4줄을 넣으면 허가 원문을 조회해 문구마다 근거 있음, 판단 보류, 원문과 충돌, 근거 없음, 해당 없음으로 판정하는 화면](docs/demo.gif)

<sub>광고 문구 및 점검 결과는 사용 방법을 보여 주기 위한 예시입니다.</sub>

> "숙취로 지끈거리는 아침에도 OK"
>
> 아세트아미노펜 진통제 광고에 이 문구가 들어가도 될까요? 허가 원문의 효능효과에 숙취는 없습니다. 사용상의 주의사항은 오히려 "알코올을 복용한 사람"에게 이 약을 먹지 말라고 적고 있습니다.

## 왜 만들었나

광고 문구를 AI로 쓰는 일이 흔해졌지만, AI는 국내 허가 사항을 모릅니다. 같은 성분이라도 나라마다 허가된 효능이 다르고, 국내 허가 원문은 학습 데이터에 거의 없습니다. 그래서 AI가 쓴 문구에는 허가받지 않은 효능이 자연스럽게 섞입니다.

의료기기법 제24조와 약사법 제68조는 허가받은 범위를 벗어난 거짓·과대 광고를 금지합니다. 광고 사전심의에서 반려되면 수정 왕복으로 일정이 밀리고, 적발되면 행정처분을 받습니다.

사람이 직접 확인하기도 번거롭습니다. 의료기기 품목명은 브랜드가 아니라 분류 이름(예: 적외선체온계)이라서 제품명으로 검색하면 허가 정보가 잘 나오지 않습니다. 의약품 효능효과는 XML 문서로 저장되어 있어 원문을 바로 읽기 어렵습니다.

이 서버는 공공데이터포털의 식약처 API에서 허가 원문을 가져와, AI가 문구를 원문과 문장 단위로 대조하고 판정마다 원문을 인용하게 합니다.

## 사용 예시

### 1. 광고 문구 점검

```
아세트아미노펜 500mg 정제(품목기준코드 198901273) 광고 문구가 허가 범위 안인지 점검해 줘.

두통, 생리통엔 한 알이면 끝!
숙취로 지끈거리는 아침에도 OK
간 걱정 없는 순한 진통제
지금 구매하면 1+1
```

이러한 요구를 작성했다면, AI는 `search_products`로 제품을 찾고, `get_permit`(`include_precautions=true`)으로 효능효과·용법용량·사용상의 주의사항 원문을 가져온 뒤 문장마다 판정합니다. 실제 결과는 아래와 같습니다(긴 메모는 줄였습니다).

> **먼저 확인할 점:** 조회된 허가 제품명은 「유니온아세트아미노펜정500밀리그람(수출용)」입니다. (…) 이 광고가 국내 소비자를 대상으로 한다면 판정 결과와 상관없이 이 품목을 국내에서 판매하고 광고해도 되는지부터 확인해야 합니다.

| #   | 문구                          | 판정        | 근거 (허가 원문 인용)                                                                      | 메모                                                                                                 |
| --- | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| 1   | 두통, 생리통엔                | 근거 있음   | "감기로 인한 발열 및 동통(통증), 두통, 신경통, 근육통, 월경통, 염좌통(삔 통증)"            | 원문 용어는 "월경통"입니다. 뜻은 같습니다.                                                           |
| 2   | 한 알이면 끝!                 | 판단 보류   | "ㆍ성인 : 아세트아미노펜으로서 1회 0.3-1.0g 1일 3-4회 경구투여한다."                       | 원문은 1일 3~4회 투여를 전제로 합니다. "끝"은 한 번에 해결된다는 뜻으로 읽혀 효과의 정도를 넓힙니다. |
| 3   | 숙취로 지끈거리는 아침에도 OK | 원문과 충돌 | "2. 다음과 같은 사람은 이 약을 복용하지 말 것 (…) 9) 알코올을 복용한 사람"                 | 원문은 알코올을 복용한 사람에게 이 약을 금기로 정합니다. "숙취"는 효능효과에도 없는 용도입니다.      |
| 4   | 간 걱정 없는                  | 원문과 충돌 | "아세트아미노펜으로 일일 최대 용량(4,000mg)을 초과할 경우 간손상을 일으킬 수 있으므로 (…)" | 간손상 경고가 있고 심한 간장애 환자에게 금기인 약을 두고 간 걱정이 없다고 말합니다.                  |
| 5   | 순한 진통제                   | 근거 없음   | (원문에 해당 표현 없음)                                                                    | "진통제"는 효능효과와 맞지만, 부작용이 적다는 주장은 원문 어디에도 없습니다.                         |
| 6   | 지금 구매하면 1+1             | 해당 없음   |                                                                                            | 효능 주장이 없는 판촉 문구입니다. 경품·증정 허용 여부는 법무 검토 대상입니다.                        |

표 아래에는 조회한 제품, 허가 원문 PDF 링크, 조회 시각과 함께 허가 원문 표현 안에서 고친 대안 문구가 붙습니다.

> - 「간 걱정 없는」 → 문구를 삭제하고 주의 문구로 대신합니다. 예: "매일 세잔 이상 정기적으로 술을 마시는 분은 복용 전 의사 또는 약사와 상의하세요. 일일 최대 용량(4,000mg)을 넘기지 마세요."
> - 「순한 진통제」 → "아세트아미노펜 성분의 해열진통제"

판정은 네 가지입니다.

| 판정        | 뜻                                                                                |
| ----------- | --------------------------------------------------------------------------------- |
| 원문과 충돌 | 허가 원문의 경고·금기·주의사항과 반대되는 말을 합니다. 가장 먼저 고쳐야 합니다.   |
| 근거 없음   | 허가 원문에 없는 효능·용도·대상을 주장합니다.                                     |
| 판단 보류   | 원문과 관련은 있지만 범위나 정도를 넓혀 말합니다("최고", "완치", "한 알이면 끝"). |
| 근거 있음   | 허가 원문에 같은 뜻의 효능·용도가 있습니다.                                       |

### 2. 의료기기 허가 원문 조회

의료기기 품목명은 "귀 적외선 체온계" 같은 분류 이름이라 브랜드로는 잘 찾히지 않습니다. 모델명을 알면 바로 찾아갑니다.

```
MC-E533 체온계가 허가받은 사용목적이 뭐야?
```

AI는 `search_products`(`by=model`)로 허가번호를 찾고 `get_permit`을 호출합니다. 서버가 돌려주는 원문은 아래와 같습니다.

```
## 귀 적외선 체온계 (한국오므론헬스케어(주))
품목허가번호: 수인 26-4414 호 · 허가일: 2026-06-15 · 최종 변경일: 2026-06-15 · 상태: 유효
등급: 2 · 분류번호: A21010.04(2) · 모델명: MC-E533외 1건 · 제조자: AViTA Corporation / AViTA (Wujiang) Co., Ltd. · 제조의뢰자: OMRON HEALTHCARE Co., Ltd.

### 사용목적 (허가 원문, 광고 문구 대조 기준)
<<<원문 시작>>>
환자의 귀 온도를 적외선 발광을 통하여 측정함으로써 체온을 측정하기 위한 측정기
<<<원문 끝>>>

출처: 식품의약품안전처, 공공데이터포털 「식품의약품안전처_의료기기 품목허가 정보」 · 조회 2026-11-14 12:23 KST
```

이 원문이 있으면 "열이 나는 원인까지 알려주는 체온계" 같은 문구가 허가받지 않은 진단 기능을 주장한다는 것을 원문 인용과 함께 말할 수 있습니다.

### 3. 이렇게도 물어볼 수 있습니다

| 질문                                                                          | AI가 쓰는 도구                                         |
| ----------------------------------------------------------------------------- | ------------------------------------------------------ |
| "이 상세페이지 문구에서 허가 범위를 벗어난 표현을 표시해 줘" (문구 붙여 넣기) | `search_products` → `get_permit`                       |
| "품목기준코드 A와 B의 효능효과가 어떻게 다른지 비교해 줘"                     | `compare_products`                                     |
| "Acetaminophen 성분 일반의약품 몇 개 찾아 줘"                                 | `search_products`(`by=ingredient`)                     |
| "이 제품 허가가 아직 유효해? 취소된 거 아니야?"                               | `get_permit` (상태와 취소·취하 경고)                   |
| "이 약을 SNS에 광고해도 돼?"                                                  | `get_permit` (전문의약품이면 약사법 제68조 제6항 경고) |
| "허가된 효능만으로 문자 캠페인 문구 3안 써 줘"                                | `get_permit` 후 원문 표현 안에서 작성                  |

## 설치

### 1. 공공데이터포털 인증키 받기

1. [공공데이터포털](https://www.data.go.kr)에 가입합니다.
2. 아래 두 API 페이지에서 각각 **활용신청**을 누릅니다. 개발계정은 보통 바로 승인되지만, 키가 게이트웨이에 반영되기까지 한 시간쯤 걸릴 수 있습니다.
   - [식품의약품안전처\_의료기기 품목허가 정보](https://www.data.go.kr/data/15057456/openapi.do)
   - [식품의약품안전처\_의약품 제품 허가정보](https://www.data.go.kr/data/15095677/openapi.do)
3. 마이페이지에서 일반 인증키를 복사합니다. Encoding 키와 Decoding 키 중 어느 것을 넣어도 서버가 알아서 맞춥니다.

### 2. MCP 클라이언트에 등록

Node.js 20.12 이상이 필요합니다.

**Claude Code**

```bash
claude mcp add korean-onlabel -e DATA_GO_KR_SERVICE_KEY=발급받은_키 -- npx -y korean-onlabel-mcp
```

Windows 네이티브 환경에서는 `npx` 앞에 `cmd /c`를 붙입니다.

```bash
claude mcp add korean-onlabel -e DATA_GO_KR_SERVICE_KEY=발급받은_키 -- cmd /c npx -y korean-onlabel-mcp
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "korean-onlabel": {
      "command": "npx",
      "args": ["-y", "korean-onlabel-mcp"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_키" }
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`)

```toml
[mcp_servers.korean-onlabel]
command = "npx"
args = ["-y", "korean-onlabel-mcp"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_키" }
```

명령으로 등록해도 같은 설정이 들어갑니다.

```bash
codex mcp add korean-onlabel --env DATA_GO_KR_SERVICE_KEY=발급받은_키 -- npx -y korean-onlabel-mcp
```

그 밖의 MCP 클라이언트(Cursor, VS Code 등)도 같은 방식으로 `npx -y korean-onlabel-mcp`를 실행하고 환경변수 `DATA_GO_KR_SERVICE_KEY`를 넘기면 됩니다.

키를 넣지 않아도 서버는 뜹니다. 도구를 호출하면 위 신청 절차를 안내하는 오류를 돌려줍니다.

## 도구

| 이름               | 종류     | 하는 일                                                                                                                                                     |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_products`  | 도구     | 제품을 찾아 식별자를 돌려줍니다. 의료기기는 품목명·모델명·업체명·허가번호, 의약품은 제품명·업체명·주성분(영문명)·허가번호로 찾습니다. 모두 부분 일치입니다. |
| `get_permit`       | 도구     | 제품 하나의 허가 원문을 자르지 않고 가져옵니다. 의료기기는 사용목적, 의약품은 효능효과와 용법용량(선택: 사용상의 주의사항)입니다.                           |
| `compare_products` | 도구     | 같은 종류의 제품 2~5개의 허가 원문을 나란히 가져옵니다.                                                                                                     |
| `review_ad_copy`   | 프롬프트 | 광고 문구와 제품을 받아 위 도구로 원문을 찾고, 문장마다 원문과 충돌 / 근거 없음 / 판단 보류 / 근거 있음 / 해당 없음으로 판정합니다.                         |

### 응답 규칙

- 허가 원문은 `<<<원문 시작>>>`과 `<<<원문 끝>>>` 사이에 담습니다. 서버 instructions에서 이 구간을 지시가 아닌 데이터로 다루도록 안내합니다.
- 결과가 없으면 `[NOT_FOUND]`로, 조회에 실패하면 `[KEY_MISSING]`, `[SERVICE_NOT_APPLIED]`, `[QUOTA_EXCEEDED]`, `[TIMEOUT]` 같은 코드로 시작합니다. AI가 조회 실패를 "허가 사항 없음"으로 잘못 답하지 않게 하기 위해서입니다.
- 취소·취하된 허가와 전문의약품(일반 대상 광고 금지, 약사법 제68조 제6항)에는 경고를 붙입니다.
- 모든 응답에 출처와 조회 시각을 붙입니다. 의약품에는 효능효과 최종 변경일과 원문 PDF 링크도 붙입니다.

### 알아 둘 점

- 식약처 API는 한 번 호출에 10~20초 걸릴 때가 있습니다. 같은 요청은 서버가 캐시해 두었다가(검색 1시간, 허가 원문 24시간) 바로 돌려줍니다.
- 의약품 주성분은 영문명(예: Acetaminophen)으로 저장되어 있습니다. 한글 성분명은 제품명 검색(`by=name`)으로 찾으세요.
- 의료기기 허가번호는 `수인 26-4414 호`처럼 공백이 들어간 형식이지만, `수인26-4414호`처럼 붙여 써도 찾습니다. 모델명 검색은 대소문자를 구분합니다.

## 함께 쓰면 좋은 서버

광고 문구를 판단하려면 규칙과 사실이 모두 필요합니다. 법령 조문을 가져오는 MCP 서버(예: korean-law-mcp)를 함께 설치하면, AI가 한 답변 안에서 "허가 원문에 없는 진단 기능을 광고하므로 의료기기법 제24조 위반 소지가 있다"처럼 허가 원문과 조문을 모두 인용합니다.

## 개발

```bash
npm install
npm test            # 고정 데이터로 도는 단위·통합 테스트
npm run typecheck
npm run build
npm run inspect     # MCP Inspector로 직접 호출
```

실제 API를 호출하는 테스트는 저장소 루트의 `.env`에 키를 넣은 뒤 실행합니다. `.env`는 git에서 제외됩니다.

```bash
cp .env.example .env   # DATA_GO_KR_SERVICE_KEY= 뒤에 키 입력
npm run test:live
```

```
src/
├── index.ts          stdio 진입점
├── server.ts         도구·프롬프트 등록 (전송 방식과 분리)
├── client.ts         공공데이터포털 호출, 키 정규화, 재시도, 캐시, 오류 변환
├── docxml.ts         의약품 허가 문서(XML)를 평문으로 변환
├── format.ts         응답 문구
├── prompts.ts        서버 instructions, review_ad_copy
└── sources/          의료기기·의약품 응답 매핑
```

## 로드맵

- v0.2: 키 없이 쓰는 원격 엔드포인트, npm 배포, CI
- v0.3: 점검 정확도 평가 세트, 허가 범위 안에서 문구를 쓰는 `write_compliant_copy`, 허가 변경 모니터링
- v0.4: 금지 표현 사전, DUR·회수 정보, 화장품·건강기능식품 검토

## 고지

- 이 서버의 점검 결과는 허가 원문 대조에 따른 1차 점검이며 법률 자문이 아닙니다. 최종 판단은 광고 사전심의와 법무 검토를 따르세요.
- 데이터 출처: 식품의약품안전처, 공공데이터포털(data.go.kr). 공공누리 이용 조건을 따릅니다.
- 이 프로젝트는 식품의약품안전처와 관련이 없는 개인 오픈소스 프로젝트입니다.

## 라이선스

MIT

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation4/5

The three tools form a clear search → fetch → compare pipeline: search_products locates identifiers, get_permit retrieves one full permit, compare_products retrieves 2-5 side by side. The only mild overlap is between get_permit and compare_products, both returning permit text, though the description clarifies the batch/contrast use case.

Naming Consistency5/5

All three names follow a consistent verb_noun snake_case pattern (search_, get_, compare_) matching their actual operations. No style mixing or vague verbs.

Tool Count4/5

Three tools is lean but each earns its place in the lookup-and-compare workflow. It is on the thin side for a data-retrieval server, but not mismatched to the focused purpose.

Completeness4/5

Core lifecycle is covered: find products, retrieve full permit text, compare candidates. Minor gaps exist (no listing of companies/classifications, no batch fetch beyond 5), but agents can work around these via search parameters.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues