Korea Public Data Catalog MCP

공개 원격 서버 기준: v0.4.0-beta.1 · 기본 런타임 모드: catalog

“무엇을 만들고 싶은지” 말하면 대한민국 공공데이터포털의 정적 목록에서 관련 데이터 이름·제공기관·형식·공식 링크를 찾고, 함께 검토할 후보를 제안하는 읽기 전용 MCP 서버입니다. Claude Custom Connector용 공개 HTTPS 서버와 직접 실행하는 로컬 서버를 함께 제공합니다.

이 프로젝트는 데이터 실행기가 아니라 메타데이터 라우터입니다. 질문할 때 공공 API를 호출하거나 파일을 내려받지 않으며, 실제 데이터 값과 실시간 정보도 제공하지 않습니다.

한눈에 보는 동작 방식

만들고 싶은 서비스 아이디어
        ↓
96,056건 정적 공공데이터 목록에서 관련 종류 검색
        ↓
데이터명 · 제공기관 · 형식 · 공식 링크와 조합 순서 제안
        ↓
사용자가 공식 페이지에서 현재성 · 이용조건 · 실제 스키마를 확인

위 그림은 이 흐름을 설명하기 위해 만든 생성형 이미지입니다. 실제 정부 시스템 화면, 공식 인증물 또는 실시간 조회 결과가 아닙니다. 이미지 생성 조건과 주의점은 이미지 자산 안내에 공개합니다.

Related MCP server: Open Data MCP

현재 카탈로그 범위

96,056건은 공식 CSV에서 (목록유형, 목록키)가 고유한 행을 엄격한 CSV 파서로 검증해 수록한 수입니다. 출처 상세 페이지는 87,581행이라고 표시합니다. 이 프로젝트는 차이 8,475건을 숨기거나 임의로 버리지 않고 두 수치를 함께 공개합니다. 어느 숫자도 대한민국 전체 공공데이터의 국가 총량이라고 주장하지 않습니다. 집계 시점이나 포털의 집계 기준 차이는 출처에서 다시 확인해야 합니다.

96,056건의 목록유형 코드는 FILE 83,695건, API 12,061건, STD 300건입니다. 이는 실제 파일 행이나 API 호출 횟수가 아니라 카탈로그 목록 건수입니다.

각 목록에는 라우팅에 필요한 최소 필드만 들어 있습니다.

• 목록키와 목록유형

• 데이터명, 제공기관, 분류체계

• 제공 형식, 업데이트 주기와 검색용 키워드

• 공식 data.go.kr URL과 출처에 표시된 이용허락범위 문구

원자료 행, 파일 내용, API 응답, 상세 설명, 담당자 연락처, 인증키는 포함하지 않습니다.

환경변수를 생략하면 catalog 모드가 실행됩니다. beta 모드는 이전 14건 fixture의 회귀 테스트를 위한 유지보수용 호환 모드이며 일반 사용자 기본값이 아닙니다.

Claude에서 가장 쉽게 시작하기

추천: 공개 원격 Custom Connector

설치나 Node.js가 필요 없습니다. Claude에 로그인한 브라우저에서 아래 링크를 열고 표시된 이름과 주소를 확인한 뒤 Add 또는 추가를 누르세요.

Claude에 Korea Public Data Catalog 추가

직접 입력할 때는 Settings/Customize → Connectors → Add custom connector에서 다음 값을 사용합니다. 화면 이름은 Claude 버전에 따라 조금 다를 수 있습니다.

이름: Korea Public Data Catalog
원격 MCP URL: https://korea-public-data-catalog-mcp-production.up.railway.app/mcp
인증: 없음

/mcp까지 포함해야 합니다. GitHub 주소, 서버 루트 주소, /health, localhost는 Connector URL이 아닙니다. 저장소에서 사전입력 링크를 다시 만들려면 다음 명령을 사용합니다. 이 명령은 scripts/print-claude-install-link.mjs를 실행해 위 링크와 같은 주소를 출력합니다.

npm run claude:install-link -- https://korea-public-data-catalog-mcp-production.up.railway.app/mcp

사용 중 HTTP 429가 표시되면 응답의 Retry-After 시간이 지난 뒤 다시 시도하세요. 네트워크 출구를 공유하는 요청은 같은 분당 횟수 묶음을 사용할 수 있습니다.

연결 후 새 채팅의 Connectors 메뉴에서 Korea Public Data Catalog를 켜고 아래 첫 테스트를 실행하세요.

로컬 대안 1: Claude Desktop Release의 .mcpb 설치

공개 서버를 통하지 않고 자신의 PC에서 실행하고 싶을 때 사용하는 방법입니다.

1. v0.3.0-beta.2 릴리스에서 korea-public-data-catalog-mcp-v0.3.0-beta.2.mcpb를 내려받습니다.

2. 파일을 더블클릭하거나 Claude Desktop으로 드래그합니다. 또는 Settings → Extensions → Advanced settings → Install Extension…에서 선택합니다.

3. 설치 후 새 채팅의 + → Connectors에서 Korea Public Data Catalog 도구를 선택합니다.

이 파일은 Windows와 macOS용으로 포장한 서명되지 않은 직접 배포 베타이므로 설치 승인 경고가 나올 수 있습니다. 릴리스의 SHA-256 파일과 다운로드한 파일의 해시를 비교할 수 있습니다.

GitHub에서 직접 배포한 Desktop Extension은 자동 업데이트되지 않습니다. 새 릴리스가 나오면 새 .mcpb를 내려받아 수동으로 다시 설치하세요. Release에 .mcpb가 아직 첨부되지 않은 버전은 아래 Claude Code 또는 수동 Desktop 설정을 사용할 수 있습니다.

로컬 대안 2: Claude Code에서 저장소의 .mcp.json 사용

Node.js 22.16 이상, Git과 Claude Code가 필요합니다. 저장소에는 프로젝트 범위 .mcp.json이 이미 있으므로 절대경로를 직접 등록할 필요가 없습니다.

git clone https://github.com/obundh/korea-public-data-catalog-mcp.git
cd korea-public-data-catalog-mcp
npm ci
npm run build
npm test
claude

처음 열 때 저장소(workspace)를 신뢰하고 프로젝트 MCP 사용을 승인합니다. Claude Code 안에서 /mcp를 실행해 korea-public-data-catalog와 7개 도구가 보이는지 확인하세요. 이 설정은 이 저장소에서 Claude Code를 실행할 때만 적용됩니다.

모든 프로젝트에서 같은 서버를 쓰고 싶다면 사용자 범위로 별도 등록할 수 있습니다. 다음 경로를 실제 저장소 절대경로로 바꾸세요.

claude mcp add --transport stdio --scope user korea-public-data-catalog -- node "E:\absolute\path\korea-public-data-catalog-mcp\dist\index.js"
claude mcp list
claude mcp get korea-public-data-catalog

원격 Custom Connector는 위 공개 서버를 사용하므로 설치와 로컬 업데이트가 필요 없습니다. .mcpb, .mcp.json, 수동 JSON 설정은 같은 7개 도구를 자신의 PC에서 실행하는 로컬 방식입니다. 두 방식 모두 96,056건 정적 스냅샷을 검색하며 실시간 공공 API를 호출하지 않습니다.

화면별 설치, 수동 설정과 문제 해결은 Claude 연결 안내를 참고하세요.

연결 후 첫 테스트

먼저 범위를 확인합니다.

현재 검색 가능한 메타데이터가 몇 건인지 알려줘. CSV에서 파싱한 수와 출처 페이지가 보고한 수를 구분하고, 어느 것도 대한민국 전체 공공데이터 총량이라고 말하지 마. 외부 API도 호출하지 마.

정상이라면 get_inventory_coverage_status를 사용해 96,056건, 87,581건, 차이 8,475건, 기준일 2026-06-30, network_access: false를 설명합니다.

그다음 만들고 싶은 것을 말합니다.

서울에서 아이 키우기 좋은 동네를 비교하는 서비스를 만들고 싶어. 어린이집, 학교, 공원, 병원, 대기질, 주택 관련 공공데이터 후보를 찾아 제공기관과 공식 링크를 보여줘. 어떤 데이터를 함께 검토할지와 빠진 항목도 설명하되, 실제 값을 조회했거나 결합이 검증됐다고 말하지 마.

또는 다음처럼 물을 수 있습니다.

부산 침수 대응 대시보드를 기획하고 싶어. 침수 이력, 강수, 배수시설, 대피소, 인구 관련 후보를 찾아 조합 순서를 제안해 줘. 서로 다른 지역·시점·코드체계일 수 있다는 점과 원자료에서 확인할 항목도 적어줘.

응답은 데이터 후보와 공식 확인 경로를 제안합니다. 실제 행을 조회하거나 스키마와 결합 키를 검증하지 않았으므로, 찾지 못한 요구와 불확실성을 구분해 읽어야 합니다.

답변은 대략 이렇게 나옵니다

실제 문장은 Claude가 정리하는 방식에 따라 달라지지만, 정상 응답에는 다음 구조가 포함됩니다.

추천 상태: 참고용 메타데이터 후보

- 어린이집: 후보 데이터명 / 제공기관 / 형식 / data.go.kr 공식 링크
- 학교: 후보 데이터명 / 제공기관 / 형식 / data.go.kr 공식 링크
- 공원: 후보 데이터명 / 제공기관 / 형식 / data.go.kr 공식 링크
- 병원·대기질·주택가격: 같은 방식의 후보와 빠진 요구

조합 전 확인:
- 실제 주소·행정동 코드와 기준 시점
- 현재 제공 상태와 인증 방식
- 이용조건, 제3자 권리와 개인정보
- 실제 필드와 결합 키

주의: 실제 값과 실시간 API를 조회하지 않았으며 결합 성공을 보증하지 않음

전기차 충전소, 부산 침수, 창업 상권, 최신값 요청, 법적 보증 요청까지 실제 도구 출력을 바탕으로 정리한 8개 예시는 복사해서 쓰는 프롬프트와 응답 예시에 있습니다.

공개 도구 7개

call_api 같은 실행 도구는 없습니다.

갱신 방식

질문할 때마다 포털을 긁지 않습니다. 저장소에 포함된 월간 정적 스냅샷을 검색하므로 속도와 결과 재현성이 높고 API 키도 필요 없습니다. 대신 포털에 새 데이터가 등록되거나 내용이 바뀌어도 자동 반영되지 않습니다.

공개 원격 Connector 사용자는 매 질문마다 갱신하거나 다시 설치할 필요가 없습니다. 프로젝트 관리자가 검증된 새 스냅샷을 서버에 배포하면 이후 요청부터 적용됩니다. Desktop Extension 사용자는 새 .mcpb를 수동으로 다시 설치하고, 소스 사용자는 저장소를 업데이트해 다시 빌드한 뒤 Claude를 재시작해야 합니다. 어느 방식이든 실제 원자료를 쓰기 전에는 응답의 공식 URL에서 게시 상태, 최신성, 이용조건, 다운로드/API 방법을 다시 확인하세요.

참고용 결과와 법적 경계

• 프로젝트 코드의 MIT License는 링크된 공공데이터나 제공기관 문서의 이용 권리를 대신 부여하지 않습니다.

• 메타데이터의 이용허락범위 문구는 출처에서 가져온 탐색 정보이며 법률의견, 이용 승인 또는 무위험 보증이 아닙니다.

• 추천은 특정 데이터의 정확성·완전성·최신성·목적 적합성이나 실제 결합 성공을 보증하지 않습니다.

• 정부, 공공데이터포털 또는 제공기관의 공식 서비스·추천·인증·제휴를 뜻하지 않습니다.

• 실제 파일/API를 취득·가공·결합·상업 이용·재배포하기 전에는 공식 페이지의 현재 조건과 제3자 권리, 개인정보 포함 여부를 직접 확인해야 합니다.

• 재난·의료·복지 등 중요한 의사결정을 이 라우팅 결과만으로 자동화하지 마세요.

자세한 원칙은 법적 안전성 설계, 개인정보 안내, 고지사항을 확인하세요. 이 문서들은 법률자문이 아닙니다.

개발 확인

npm run check
npm test
npm run inventory:check
npm run inventory:test:legal-compliance
npm pack --dry-run --json --ignore-scripts

로컬에서 MCP 프로토콜과 도구 목록을 눈으로 확인하려면 다음을 실행합니다.

npm run inspect

자동 테스트는 MCP 프로토콜과 도구 응답을 검증합니다. Claude 앱의 설치·로그인 상태는 사용자 환경마다 다르므로 실제 연결은 위 확인 명령과 테스트 프롬프트로 점검하세요.

Desktop Extension 유지보수

릴리스 관리자는 검증된 전용 staging 절차로 .mcpb와 SHA-256 파일을 만듭니다.

npm run desktop:pack

desktop-extension/manifest.json을 template으로 사용한 결과가 artifacts/에 생성됩니다. 저장소 루트 전체에 mcpb pack을 실행하거나 전체 저장소를 확장 번들로 압축하지 마세요. 전용 스크립트는 공개 runtime, 정적 catalog, 필요한 문서와 production 의존성만 staging해 내부 인벤토리·raw 자료·테스트·개발 파일이 bundle에 섞이지 않게 합니다.

문서와 신고

• 초보자 안내서

• Claude 연결 안내

• 원격 배포·운영 안내

• 복사해서 쓰는 프롬프트와 응답 예시

• 생성형 이미지 자산 안내

• 법적 안전성 설계

• 개인정보 안내

• 정정·차단 요청

• 보안·민감정보 신고

• 고지사항

일반 오류와 공개 메타데이터 정정은 GitHub Issues로 제안할 수 있습니다. 비밀값, 개인정보, 보안 취약점은 공개 이슈에 원문을 쓰지 말고 GitHub 비공개 취약점 신고를 사용하세요.