HIRA Disease MCP

건강보험심사평가원 질병정보서비스를 Claude custom connector에서 바로 쓰기 위한 원격 MCP 서버입니다.

한의사 대상 강의에서 사용할 수 있도록 기본값은 medTp=2 한방 기준으로 잡았습니다. 의과(양방) 기준으로 조회하려면 medTp=1을 사용하면 됩니다.

Quick Start For Claude

Claude custom connector에 넣을 주소는 아래 둘 중 하나입니다.

Option A. 공개 서버를 바로 쓰는 경우

대부분의 사용자는 아래 주소만 복사해서 Claude custom connector에 넣으면 됩니다.

https://hira-disease-mcp.vercel.app/mcp?oc=YOUR_DATA_GO_KR_SERVICE_KEY

여기서 바꾸는 부분은 마지막의 YOUR_DATA_GO_KR_SERVICE_KEY뿐입니다.

공공데이터포털 인증키는 가능하면 Encoding 인증키를 사용하세요. 인증키에 +, /, = 같은 문자가 들어가면 URL에서 깨질 수 있습니다.

Option B. 강의자가 별도 도메인을 제공한 경우

강의자가 hiradisease.vercel.app 같은 별도 주소를 제공했다면 그 주소를 그대로 사용하세요.

https://hiradisease.vercel.app/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY

법률 MCP처럼 짧은 파라미터도 지원합니다.

https://hiradisease.vercel.app/mcp?oc=YOUR_DATA_GO_KR_SERVICE_KEY

Option C. 직접 배포해서 쓰는 경우

위의 Deploy with Vercel 버튼을 눌러 본인 Vercel에 배포합니다.

배포가 끝나면 Vercel이 이런 주소를 줍니다.

https://your-project-name.vercel.app

그 주소 뒤에 /mcp?key=본인_API키를 붙입니다.

https://your-project-name.vercel.app/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY

What Is YOUR_DOMAIN?

YOUR_DOMAIN은 직접 입력하는 단어가 아닙니다.

MCP 서버가 배포된 실제 인터넷 주소를 뜻합니다.

Situation	Connector URL
공개 서버 바로 사용	https://hira-disease-mcp.vercel.app/mcp?oc=YOUR_DATA_GO_KR_SERVICE_KEY
강의자가 별도 도메인을 제공	https://hiradisease.vercel.app/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY
내 Vercel 프로젝트 사용	https://your-project-name.vercel.app/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY
내 커스텀 도메인 사용	https://my-domain.com/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY

즉, README나 예시에서 보이는 YOUR_DOMAIN은 아래 부분입니다.

https://YOUR_DOMAIN/mcp?key=...
        ^^^^^^^^^^^
        실제 배포 도메인

처음 사용하는 사람은 YOUR_DOMAIN을 직접 고민하지 말고, 강의자가 제공한 완성 URL 또는 Vercel 배포 후 나온 URL을 복사하면 됩니다.

What It Does

• 질병명/상병코드 검색
• 질병 성별·연령별 통계 조회
• 질병 입원·외래별 통계 조회
• 질병 의료기관 종별 통계 조회
• 질병 의료기관 지역별 통계 조회

공공데이터포털의 건강보험심사평가원_질병정보서비스는 XML REST API이며, 질병명칭/코드조회와 여러 질병 통계를 제공합니다.

Source: https://www.data.go.kr/data/15119055/openapi.do

Who Can Use This?

한의사만 사용할 수 있는 도구가 아닙니다.

HIRA 질병정보서비스는 의과(양방)·한방 구분값을 제공하므로, 한의사뿐 아니라 의사, 보건의료 연구자, 보험·심사 관련 실무자, 의료 데이터 교육자도 사용할 수 있습니다.

medTp 값은 아래처럼 사용합니다.

medTp	Meaning
1	의과(양방)
2	한방

이 repo는 한의사 강의용 편의를 위해 기본값만 medTp=2로 둔 것이고, 도구 입력에서 medTp=1을 지정하면 의과 기준으로 조회할 수 있습니다.

Claude Connector URL Formats

이 서버는 아래 형식을 모두 지원합니다.

https://DEPLOYED_DOMAIN/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY
https://DEPLOYED_DOMAIN/mcp?oc=YOUR_DATA_GO_KR_SERVICE_KEY
https://DEPLOYED_DOMAIN/mcp?serviceKey=YOUR_DATA_GO_KR_SERVICE_KEY

고급 사용자는 헤더 방식도 사용할 수 있습니다.

x-api-key: YOUR_DATA_GO_KR_SERVICE_KEY
Authorization: Bearer YOUR_DATA_GO_KR_SERVICE_KEY

URL 쿼리에 API 키를 넣으면 브라우저 기록, 프록시 로그, 배포 플랫폼 로그에 남을 수 있습니다. 강의용·개인용 연결에는 편하지만 공개 공유는 하지 마세요.

Get A Service Key

1. https://www.data.go.kr 접속
2. 회원가입 또는 로그인
3. 건강보험심사평가원 질병정보서비스 검색
4. 원하는 Open API 선택
5. 활용신청 클릭
6. 개발단계로 신청
7. 마이페이지 → 개발계정 → 인증키 확인
8. Claude connector URL의 key= 또는 oc= 뒤에 입력

Claude connector URL에는 가능하면 Encoding 인증키를 넣으세요.

공공데이터포털 안내에 따르면 개발계정은 자동승인이고, 개발계정 트래픽은 10,000건입니다.

Tools

hira_search_disease

질병명 또는 상병코드로 HIRA 질병 정보를 검색합니다.

Example:

{
  "searchText": "요추염좌",
  "diseaseType": "SICK_NM",
  "medTp": 2,
  "numOfRows": 10
}

hira_disease_gender_age_stats

상병코드 기준 성별·연령별 통계를 조회합니다.

{
  "sickCd": "J00",
  "year": 2024,
  "medTp": 2
}

hira_disease_inout_stats

상병코드 기준 입원·외래별 통계를 조회합니다.

hira_disease_institution_type_stats

상병코드 기준 의료기관 종별 통계를 조회합니다.

hira_disease_region_stats

상병코드 기준 의료기관 지역별 통계를 조회합니다.

Example Questions For Claude

처음 사용할 때는 한방, 의과만 쓰기보다 medTp 값을 함께 적어주면 더 안전합니다.

공식 명세 기준:

기준	medTp
의과(양방)	1
한방	2

HIRA 질병정보 MCP로 요추염좌를 한방 기준, 즉 medTp=2로 검색하고 관련 상병코드를 알려줘.

J00 상병코드의 2024년 한방 기준, 즉 medTp=2 성별·연령별 통계를 요약해줘.

감기 관련 상병을 한방 기준, 즉 medTp=2로 검색한 뒤 한의원 강의에서 설명하기 좋게 정리해줘.

HIRA 질병정보 MCP로 요추염좌 관련 질병을 먼저 검색해줘. 그 다음 적절한 상병코드를 골라서 한방 기준 medTp=2와 의과 기준 medTp=1의 2024년 성별·연령별 통계를 비교해줘.

HIRA 질병정보 MCP로 요추염좌 관련 상병코드를 찾고, 한방 기준 medTp=2와 의과 기준 medTp=1에서 입원·외래 통계가 어떻게 다른지 비교해줘. 강의에서 설명하기 쉽게 핵심만 정리해줘.

HIRA 질병정보 MCP가 연결되어 있는지 확인하고, 사용할 수 있는 도구 목록과 각 도구로 할 수 있는 일을 짧게 설명해줘.

Deploy To Vercel

가장 쉬운 방법은 README 상단의 Deploy with Vercel 버튼을 누르는 것입니다.

CLI로 직접 배포하려면:

npm install
npm run build
npx vercel

Vercel에 배포되면 /mcp가 /api/mcp로 rewrite됩니다.

https://YOUR_PROJECT.vercel.app/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY

Claude connector에는 Vercel 프로젝트 홈 주소가 아니라, 반드시 /mcp?key=...까지 붙인 주소를 넣어야 합니다.

Local Development

npm install
npm run dev

Health check:

curl http://localhost:3000/health

MCP endpoint:

http://localhost:3000/mcp?key=YOUR_DATA_GO_KR_SERVICE_KEY

Local Stdio MCP

For Claude Desktop or local MCP clients:

{
  "mcpServers": {
    "hira-disease": {
      "command": "npx",
      "args": ["hira-disease-mcp"],
      "env": {
        "HIRA_SERVICE_KEY": "YOUR_DATA_GO_KR_SERVICE_KEY"
      }
    }
  }
}

Notes

• HIRA changed the disease API base path to diseaseInfoService1 and operation names ending in 1.
• This server uses getDissNameCodeList1, getDissByGenderAgeStats1, getDissByHsptlzFrgnStats1, getDissByClassesStats1, and getDissByAreaStats1.
• HIRA medTp code: 1 = medicine/western medicine, 2 = Korean medicine.
• The default medTp=2 is intended for Korean medicine lecture use cases.

License

MIT