국민건강보험 공공데이터 MCP — 건강보험 API를 Claude에 연결하는 가이드

Q: Claude Desktop에서도 사용할 수 있나요?

네, Claude Desktop에서도 설정할 수 있습니다. 맥OS 기준으로 ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 열어 mcpServers 블록에 동일한 설정을 추가하면 됩니다.

Q: uv 혹은 uvx가 설치되지 않으면 어떻게 하나요?

uvx는 uv 패키지 매니저에 포함된 명령어입니다. macOS·Linux에서는 터미널에서 curl -LsSf https://astral.sh/uv/install.sh | sh 를 실행해 설치할 수 있습니다. Windows는 공식 문서(docs.astral.sh/uv)를 참고하세요.

국민건강보험공단이 공개한 공공데이터 API를 MCP(Model Context Protocol) 서버로 Claude 같은 AI 도구에 연결하면, 자연어 한 줄로 건강보험 통계·사업장 가입 현황·요양기관 정보 등을 바로 조회할 수 있습니다. 핵심은 공공데이터포털(data.go.kr)에서 API 키를 발급받고, 공공데이터포털 MCP 서버 모음을 AI 클라이언트에 등록하는 것입니다. 이 가이드는 키 발급부터 설정·실제 활용까지 전 과정을 단계별로 다룹니다.

왜 건강보험 공공데이터를 MCP로 연결하는가

국민건강보험공단과 관련 기관은 다양한 공공 API를 data.go.kr에 공개하고 있습니다. 그러나 이 데이터를 실무에 활용하려면 API 문서를 읽고, HTTP 요청을 직접 만들고, 응답 JSON을 파싱하는 반복 작업이 필요합니다. MCP 서버를 중간에 두면 이 과정을 AI가 대신 처리합니다. 사용자는 “이 회사 직원 몇 명이 건강보험에 가입돼 있어?” 처럼 자연어로 질문하고, AI가 API를 호출해 결과를 정리해 줍니다.

사용자 (자연어 질문)
        │
        ▼
AI 클라이언트 (Claude / Cursor)
        │  MCP 프로토콜
        ▼
MCP 서버 (data-go-mcp-servers)
        │  HTTP REST API 호출
        ▼
공공데이터포털 API (data.go.kr)
        │
        ▼
국민건강보험공단 / 국민연금공단 데이터

이 구조 덕분에 API 스펙을 외우지 않아도 되고, 여러 API를 조합한 분석도 자연어 대화로 처리할 수 있습니다.

어떤 건강·연금 관련 데이터를 쓸 수 있나

공공데이터포털에서 제공하는 건강보험·연금 관련 주요 오픈 API는 다음과 같습니다.

제공 기관	데이터	활용 예
국민연금공단	사업장 가입자 현황	특정 사업자의 연금 가입 직원 수 확인
국민건강보험공단	요양기관 정보	지역별 병원·약국 목록 조회
국민건강보험공단	건강검진 통계	연도별 검진 수검률 분석
국민건강보험공단	직장 가입자 보험료	보험료 기준 급여 추정
건강보험심사평가원	의약품 정보	처방 의약품 성분·효능 검색

공공데이터 카테고리 전체 보기에서 더 많은 한국 공공 API MCP 서버를 확인하실 수 있습니다.

준비물

인터넷 연결이 되는 PC(macOS, Linux, Windows 모두 지원)
Claude Code, Cursor, 또는 Claude Desktop 중 하나
data.go.kr 계정(무료)
uv 패키지 관리자(Python 3.8 이상 포함)

단계별 설치 및 설정

1단계 — data.go.kr 회원가입 및 API 키 발급

공공데이터포털(data.go.kr)에 접속해 회원가입합니다.
로그인 후 상단 검색창에 원하는 서비스명(예: “국민연금 사업장 가입” 또는 “건강보험 요양기관”)을 입력합니다.
검색 결과에서 오픈 API 탭을 선택하고, 원하는 API의 “활용신청” 버튼을 클릭합니다.
활용 목적을 간단히 입력하고 신청을 완료합니다. 대부분 즉시 또는 1영업일 이내에 승인됩니다.
마이페이지 → “오픈API” → “개발계정” 탭에서 **일반 인증키(Encoding)**를 복사합니다.

이 인증키는 이후 MCP 서버 환경변수에 사용하므로 안전한 곳에 보관하세요.

2단계 — uv 설치

data-go-mcp-servers는 uvx 명령으로 실행합니다. uv가 없다면 먼저 설치합니다.

macOS 또는 Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널을 재시작하거나 아래 명령으로 경로를 즉시 적용합니다.

source $HOME/.local/bin/env

설치 확인:

uvx --version

버전 번호가 출력되면 정상입니다.

3단계 — MCP 클라이언트 설정 파일에 서버 등록

Claude Code

~/.claude/settings.json 파일을 열고 mcpServers 블록에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "nps-business-enrollment": {
      "command": "uvx",
      "args": ["data-go-mcp.nps-business-enrollment@latest"],
      "env": {
        "DATA_GO_KR_API_KEY": "발급받은_인증키를_여기에"
      }
    }
  }
}

Claude Desktop (macOS)

설정 파일 경로: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nps-business-enrollment": {
      "command": "uvx",
      "args": ["data-go-mcp.nps-business-enrollment@latest"],
      "env": {
        "DATA_GO_KR_API_KEY": "발급받은_인증키를_여기에"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json 파일에 동일한 mcpServers 블록을 추가합니다.

주의: 발급받은_인증키를_여기에 부분을 1단계에서 복사한 실제 인증키로 반드시 교체하세요. 키는 URL 인코딩된(Encoding) 값을 사용합니다.

4단계 — 클라이언트 재시작 및 연결 확인

설정 파일을 저장한 뒤 AI 클라이언트를 완전히 재시작합니다.

Claude Code: 터미널에서 /mcp 명령을 입력하면 등록된 MCP 서버 목록과 connected 상태가 표시됩니다.
Cursor: Settings(설정) → MCP 탭에서 서버 이름 옆 상태 표시가 초록색인지 확인합니다.
Claude Desktop: 채팅창 하단에 망치 아이콘이 생기면 MCP 도구가 활성화된 것입니다.

연결이 안 된다면 아래 흔한 오류 섹션을 참고하세요.

5단계 — 자연어로 건강보험·연금 데이터 조회

연결이 완료되면 다음과 같은 자연어 프롬프트를 시도해 보세요.

“사업자등록번호 123-45-67890 사업장의 국민연금 가입 직원 수를 알려줘”
“이 회사가 data.go.kr 공공 API로 조회 가능한 연금 가입 정보를 보여줘”
“국민건강보험 관련 공공데이터 API 중 어떤 것을 활용할 수 있는지 정리해줘”

AI가 MCP 서버의 도구를 호출해 data.go.kr API에 직접 요청을 보내고, 결과를 사람이 읽기 쉬운 형태로 정리해 드립니다.

흔한 오류와 해결 방법

오류 증상	원인	해결 방법
`uvx: command not found`	uv 미설치 또는 PATH 미적용	2단계 설치 명령 재실행 후 터미널 재시작
`SERVICE_KEY_IS_NOT_REGISTERED_ERROR`	API 키 오류 또는 미승인	data.go.kr 마이페이지에서 승인 상태 확인, 인코딩 키 사용 여부 점검
MCP 서버 목록에 미표시	설정 파일 JSON 형식 오류	JSON 문법 검사기(jsonlint.com 등)로 설정 파일 점검
`DAILY_TRAFFIC_EXCEED`	일일 호출 한도 초과	data.go.kr에서 해당 API의 트래픽 연장 신청 또는 다음 날 재시도
연결됐지만 데이터 없음	사업자번호 형식 오류	하이픈 없는 10자리 숫자 형식으로 입력

추가 활용: 다른 공공 API와 조합하기

data-go-mcp-servers는 국민연금 API 외에도 다양한 공공 API를 지원합니다. 예를 들어 국세청 사업자등록 진위 확인 API와 국민연금 사업장 가입 API를 함께 쓰면, 특정 사업자가 실제로 등록된 법인인지 확인하고 직원 규모를 동시에 파악하는 분석이 가능합니다.

한국 부동산 데이터가 필요하다면 한국 부동산 MCP를 함께 활용하면 지역별 요양기관 수와 주거 환경을 교차 분석하는 것도 가능합니다. 표준국어대사전 API가 필요한 경우에는 표준국어대사전 MCP 서버도 확인해 보세요.

더 많은 한국 공공데이터 MCP 서버 목록은 공공데이터 카테고리에서, 전체 서버 목록은 MCP 서버 디렉토리에서 확인하실 수 있습니다.

자주 묻는 질문

국민건강보험 공공데이터 API는 무료인가요?

네, 공공데이터포털(data.go.kr)에서 제공하는 대부분의 공공 API는 무료입니다. 회원가입 후 API 활용 신청을 하면 인증키를 무상으로 발급받을 수 있습니다. 다만 API마다 일일 호출 한도가 다르므로, 신청 페이지에서 제공 횟수를 확인하세요.

data-go-mcp-servers가 건강보험 API를 직접 지원하나요?

data-go-mcp-servers는 현재 국민연금공단 사업장 가입 API, 국세청 사업자등록 진위 확인 API, 조달청 나라장터 API 등을 포함합니다. 국민건강보험공단이 data.go.kr에 공개한 개별 API는 직접 HTTP 호출 방식으로 활용하거나, MCP 서버를 직접 구현해 연결할 수 있습니다.

Claude Desktop에서도 사용할 수 있나요?

네, Claude Desktop에서도 설정할 수 있습니다. macOS 기준으로 ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 열어 mcpServers 블록에 동일한 설정을 추가하면 됩니다.

API 키가 없어도 먼저 테스트할 수 있나요?

일부 공공 API는 샘플 키나 미리보기 기능을 제공하지만, 안정적인 활용을 위해서는 data.go.kr에서 정식 인증키를 발급받는 것을 권장합니다. 발급은 보통 즉시~1영업일 이내에 완료됩니다.

uv 혹은 uvx가 설치되지 않으면 어떻게 하나요?

uvx는 uv 패키지 매니저에 포함된 명령어입니다. macOS·Linux에서는 터미널에서 curl -LsSf https://astral.sh/uv/install.sh | sh 를 실행해 설치할 수 있습니다. Windows는 공식 문서(docs.astral.sh/uv)를 참고하세요.

건강보험 관련 어떤 데이터를 조회할 수 있나요?

공공데이터포털에서 제공하는 국민건강보험 관련 데이터로는 사업장별 건강보험 가입 현황, 지역별 보험료 부과 통계, 요양기관 정보, 건강검진 통계 등이 있습니다. 각 API는 data.go.kr에서 ‘건강보험’으로 검색해 확인할 수 있습니다.

다음 단계

이 가이드를 통해 국민건강보험·연금 공공데이터를 AI 도구에 연결하는 기본 설정을 마쳤습니다. 다음으로는:

공공데이터포털 MCP 서버 모음 상세 페이지에서 지원하는 API 전체 목록 확인
공공데이터 카테고리에서 다른 한국 공공 API MCP 서버 탐색
MCP 서버 제출을 통해 직접 만든 건강보험 MCP 서버를 MCP모아에 등록

건강보험·연금 데이터를 넘어 더 많은 한국 공공 데이터를 AI와 연결하고 싶다면, MCP 서버 전체 목록을 둘러보세요.