kr-medicine-mcp

식품의약품안전처(MFDS) 공개 API를 MCP 도구 10개로 노출하는 서버입니다. 의약품 검색·상호작용·임부금기 검증과 식품 영양·알레르기·회수 정보를 Claude Desktop, Cursor, Claude Code 등 MCP 호환 클라이언트에서 바로 사용할 수 있습니다.

왜 만들었나

LLM은 한국 약품명·성분·DUR(약물 안전사용) 정보를 잘 모릅니다. "이트라코나졸이랑 심바스타틴 같이 먹어도 되나"를 물으면 그럴듯하게 지어내기 쉬운데, 의료 영역에서 틀린 답은 사람을 다치게 할 수 있습니다.

사용자: "이트라코나졸이랑 심바스타틴 같이 먹어도 돼?"

LLM 단독:    "둘 다 흔한 처방약입니다. 큰 문제는 없을 것으로 보이지만
             의사 상담을 권장합니다."          ← 환각

LLM + MCP:   ⚠️ 병용금기 — 횡문근융해증 위험
             출처: 식약처 DUR 품목정보
             → 의사·약사 상담 필수

이 서버는 모든 답을 식약처 공식 DB와 교차검증합니다. 진단·처방은 범위 밖이며, 조회된 사실만 전달하고 전문가 상담을 안내합니다.

도구 10개

의약품 (7개)

| 도구 | 역할 | API | |---|---|---| | search_drug | 약 이름/성분으로 검색 → 품목코드 획득 | e약은요 | | get_drug_detail | 효능·용법·주의·상호작용·부작용 풀세트 | e약은요 | | find_alternatives | 동일 주성분 다른 제품 | e약은요 | | check_interaction | 두 약 병용금기 직접 검증 | DUR 품목정보 | | check_pregnancy_safety | 임부금기 + 사유 | DUR 품목정보 | | check_age_caution | 노인주의 + 특정연령대금기 | DUR 품목정보 | | identify_pill | 모양·색상·각인으로 약 식별 | 의약품 낱알식별 |

식품 (3개)

| 도구 | 역할 | API | |---|---|---| | search_food_nutrition | 식품 칼로리·영양성분 조회 | 식품영양성분 DB | | check_food_allergen | 가공식품 원재료·알레르기 유발물질 확인 | 식품안전나라 | | get_food_recall | 회수·판매중지 식품 조회 | 식품안전나라 |

search_food_nutrition 은 MFDS_API_KEY 로 동작합니다. check_food_allergen·get_food_recall 은 별도의 FOOD_SAFETY_API_KEY(식품안전나라) 가 있을 때만 활성화되며, 없으면 이 두 도구만 안내 메시지를 반환하고 나머지는 정상 작동합니다.

사용 예시

일상 대화에서 다음과 같이 물으면, 모델이 적절한 도구를 골라 식약처 DB를 조회한 뒤 답합니다.

약물 상호작용 — LLM이 가장 위험하게 틀리는 영역

"이트라코나졸이랑 심바스타틴 같이 먹어도 돼?"
  → check_interaction: 병용금기(횡문근융해증 위험) 탐지, 사유·출처 제시

"지금 와파린 먹는 중인데 아스피린 추가해도 되나?"
  → 기존 복용약 대비 신규 약 병용금기 교차검증

다제 복용 점검 (고령자)

"75세 어머니가 클로르페니라민, 디아제팜, 아미트립틸린을 같이 드세요. 괜찮을까요?"
  → check_age_caution + check_interaction:
    노인주의 성분 + 약물 간 금기를 한 번에 점검

임신 중 복용

"임신 12주인데 감기약에 아미노필린 들어있어. 안전해?"
  → check_pregnancy_safety: 임부금기 등급과 사유 조회
    (DB 미등재가 곧 '안전'은 아님을 명시)

정체불명 알약 식별

"서랍에서 나온 흰색 둥근 알약, 한쪽 면에 'TYL 500' 각인됐어. 이거 뭐야?"
  → identify_pill: 모양·색상·각인으로 품목 특정

대체약 탐색 (품절·성분 동일)

"타이레놀이 약국에 없대. 같은 성분 다른 제품 알려줘"
  → find_alternatives: 동일 주성분 제품 목록

식품 안전

"우리 애가 땅콩 알레르기 있는데, 이 과자 먹여도 돼?"
  → check_food_allergen: 가공식품 원재료·알레르기 유발물질 확인

"OO 제품 회수됐는지 확인해줘"
  → get_food_recall: 회수·판매중지 처분 식품 조회

진단·처방 권고는 의료 안전상 일부러 거부하고, 의사·약사 상담이 필요한 영역으로 안내합니다.

설치

0단계: API 키 발급 (무료)

(1) 공공데이터포털 — data.go.kr 회원가입 후 다음 6개를 검색해서 활용신청 (모두 자동승인). 마이페이지의 인증키(Decoding 버전) 하나를 MFDS_API_KEY 로 사용합니다:

• 식품의약품안전처 의약품개요정보(e약은요)
• 식품의약품안전처 의약품 제품 허가정보
• 식품의약품안전처 의약품안전사용서비스(DUR) 품목정보
• 식품의약품안전처 의약품안전사용서비스(DUR) 성분정보
• 식품의약품안전처 의약품 낱알식별 정보
• 식품의약품안전처 식품영양성분 DB (search_food_nutrition 용)

(2) 식품안전나라 (선택) — foodsafetykorea.go.kr 회원가입 → 활용신청(즉시 발급). check_food_allergen·get_food_recall 사용 시에만 필요하며 FOOD_SAFETY_API_KEY 로 사용합니다. 없으면 이 두 도구만 비활성화됩니다.

설치할 필요 없이 npx 로 바로 실행됩니다.

방법 1: Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows) 편집:

{
  "mcpServers": {
    "kr-medicine": {
      "command": "npx",
      "args": ["-y", "kr-medicine-mcp"],
      "env": {
        "MFDS_API_KEY": "발급받은_인증키_Decoding",
        "FOOD_SAFETY_API_KEY": "식품안전나라_키 (선택)"
      }
    }
  }
}

저장 후 Claude Desktop 을 완전히 종료했다가 재실행합니다.

방법 2: Claude Code

claude mcp add kr-medicine \
  --env MFDS_API_KEY=발급받은_인증키 \
  --env FOOD_SAFETY_API_KEY=식품안전나라_키 \
  -- npx -y kr-medicine-mcp

방법 3: 직접 빌드 (개발용)

git clone https://github.com/zzjiho/kr-medicine-mcp.git
cd kr-medicine-mcp
npm install
npm run build

cp .env.example .env
# .env 파일을 열어 MFDS_API_KEY=... 입력

개발

npm install
npm run build              # tsc 컴파일
npm run watch              # tsc --watch
bash test-all-tools.sh     # 도구 종합 회귀 테스트

자세한 시나리오는 TESTING.md 참고.

아키텍처

src/
├── core/        defineTool 헬퍼 + 미들웨어 합성 (캐시·면책·에러)
├── shared/      HTTP 클라이언트, TTL 캐시
├── domains/
│   ├── drug/    e약은요 (search · detail · alternatives)
│   ├── dur/     DUR 안전사용 (interaction · pregnancy · age-caution)
│   ├── pill/    낱알식별 (identify)
│   └── food/    식품 (nutrition · allergen · recall)
└── server.ts    MCP stdio / HTTP 부팅 + DI 컨텍스트

도메인 기반 구조 + 미들웨어 자동 합성. 새 도구는 도메인 폴더에 *.tool.ts 파일 하나만 추가하면 등록·면책·캐싱·에러 처리가 자동으로 붙습니다.

stdio(로컬 클라이언트) 와 HTTP/SSE(원격 배포) 두 가지 트랜스포트를 지원합니다 (MCP_MODE=http).

⚠️ 의료 면책

본 정보는 식약처 공식 데이터에 기반한 참고용입니다.

• 실제 복용 전 반드시 의사·약사와 상담하세요.
• 응급 상황은 119에 즉시 연락하세요.
• 진단·처방 등 의료 전문 영역은 본 도구의 범위 밖입니다.
• DB 미등재가 안전을 의미하지는 않습니다 — 등록되지 않은 위험이 있을 수 있습니다.

본 도구의 답변은 의료진의 전문적 판단을 대체할 수 없습니다.

라이선스

MIT

출처

• 식약처 의약품개요정보(e약은요) — 공공데이터포털
• 식약처 의약품 제품 허가정보 — 공공데이터포털
• 식약처 의약품안전사용서비스(DUR) 품목정보 — 공공데이터포털
• 식약처 의약품안전사용서비스(DUR) 성분정보 — 공공데이터포털
• 식약처 의약품 낱알식별 정보 — 공공데이터포털
• 식약처 식품영양성분 DB — 공공데이터포털
• 식약처 가공식품 원재료·알레르기 정보 — 식품안전나라
• 식약처 회수·판매중지 식품 정보 — 식품안전나라