공공데이터포털 API 키는 어떻게 발급받나요?

data.go.kr에 회원가입한 뒤, 원하는 데이터셋 페이지에서 '활용신청' 버튼을 클릭하면 됩니다. 일반 공개 API는 신청 즉시 또는 1~2일 내 승인되며, 마이페이지 > 오픈API에서 인증키를 확인할 수 있습니다.

MCP 서버를 직접 만들지 않고 기존 서버를 쓸 수는 없나요?

있습니다. 이 글에서 소개하는 real-estate-mcp나 data-go-mcp-servers처럼 이미 공개된 서버를 GitHub에서 클론하거나 uvx로 설치해 API 키만 넣으면 바로 사용할 수 있습니다.

공공데이터 API에 CORS 문제가 있어 브라우저에서 직접 호출이 안 되는데, MCP는 괜찮나요?

MCP 서버는 서버사이드(Node.js 또는 Python 프로세스)에서 공공 API를 호출하므로 브라우저 CORS 제한과 무관합니다. Claude Desktop이 stdio로 MCP 서버를 호출하고, 서버가 대신 공공 API에 HTTP 요청을 보내는 구조입니다.

API 응답이 XML인 경우 어떻게 처리하나요?

공공데이터포털 API는 기본적으로 XML을 반환하는 경우가 많습니다. Node.js에서는 fast-xml-parser, Python에서는 xmltodict 라이브러리로 JSON으로 변환한 뒤 필요한 필드만 추출해 Claude에 반환하면 됩니다.

MCP 서버를 Claude Code(CLI)와 Claude Desktop 양쪽에서 모두 쓸 수 있나요?

네. stdio 방식의 MCP 서버는 Claude Desktop의 claude_desktop_config.json 또는 Claude Code CLI의 설정 파일에 등록하면 두 클라이언트 모두에서 동일하게 사용할 수 있습니다.

호출 횟수 제한(Rate Limit)이 걱정됩니다.

공공데이터포털 API는 기본 일일 10,000~100,000건 한도가 설정되는 경우가 많습니다. MCP 서버 코드 안에서 응답을 메모리나 SQLite에 캐시하거나, 동일 요청이 반복될 때 캐시를 우선 반환하도록 구현하면 실제 API 호출 수를 크게 줄일 수 있습니다.

공공데이터 OpenAPI를 MCP 서버로 만들어 Claude에 연결하기

한국 공공데이터포털(data.go.kr)의 OpenAPI를 MCP(Model Context Protocol) 서버로 감싸면, Claude가 “이 사업자등록번호가 유효한지 확인해 줘”나 “이 아파트 최근 실거래가 알려 줘” 같은 자연어 요청을 받았을 때 실시간 공공 데이터를 직접 조회해 답합니다. 이 글은 두 가지 경로를 모두 다룹니다 — 이미 공개된 서버를 클론해 인증키만 넣고 바로 쓰는 방법과, 원하는 API를 직접 MCP 서버로 만드는 방법입니다.

왜 MCP로 연결하는가

Claude는 학습 마감 시점 이후의 정보를 모릅니다. 오늘의 아파트 실거래가, 방금 신청된 사업자등록 상태, 최신 조달청 입찰 공고는 모델 가중치 안에 없습니다. 검색으로 끌어올 수 있는 정보도 있지만, 공공데이터포털 API는 구조화된 원본 레코드를 정확한 필드 단위로 돌려준다는 점이 다릅니다.

MCP 서버는 이 API를 Claude가 호출할 수 있는 “도구(tool)“로 노출하는 표준 인터페이스입니다. 한 번 연결해 두면 Claude가 질문 맥락에 맞춰 알아서 도구를 골라 호출하고, 응답을 해석해 답을 만듭니다. 데이터셋은 행정·교통·의료·환경·금융 등 카테고리에 걸쳐 있으며 대부분 무료로 활용신청할 수 있습니다.

전체 호출 흐름은 다음과 같습니다.

사용자 자연어 질문
       │
       ▼
Claude (MCP 클라이언트)
       │  MCP 도구 호출 (stdio)
       ▼
MCP 서버 (Node.js / Python)
       │  HTTP 요청 + serviceKey
       ▼
공공데이터포털 OpenAPI (data.go.kr)
       │  JSON / XML 응답
       ▼
MCP 서버 (파싱·정제)
       │  구조화된 결과 반환
       ▼
Claude → 사용자에게 자연어 답변

핵심은 MCP 서버가 서버사이드 프로세스라는 점입니다. 브라우저가 아니라 Node.js나 Python 프로세스가 공공 API를 호출하므로, 공공데이터 API의 CORS 제약과 무관하게 동작합니다.

경로 A — 공개된 MCP 서버로 5분 만에 시작하기

직접 코드를 쓰기 전에, 이미 공개된 서버로 목적이 충족되는지 먼저 확인하는 것이 효율적입니다. 아래 세 서버는 data.go.kr 기반 MCP 서버 중 대표적으로 쓰이는 사례입니다.

서버	연결 API	설치 방식	인증키
한국 부동산 MCP	국토교통부 실거래가, 청약홈, 온비드	GitHub 클론 → stdio	필요
공공데이터포털 MCP 서버 모음	국민연금·국세청·조달청·금감원 등	uvx	필요
표준국어대사전 MCP	국립국어원 표준국어대사전	GitHub 클론 → stdio	불필요

공공데이터포털 MCP 서버 모음 (uvx)

data-go-mcp-servers는 국민연금공단 사업장 가입 조회, 국세청 사업자등록 진위 확인, 조달청 나라장터, 금융감독원 기업재무정보 등을 API별 모듈로 나눠 제공합니다. 필요한 모듈만 골라 실행하면 됩니다. 아래는 국민연금 사업장 가입 모듈 예시입니다.

uvx data-go-mcp.nps-business-enrollment@latest

Claude Desktop 설정 파일(macOS 기준 ~/Library/Application Support/Claude/claude_desktop_config.json)에 다음을 추가합니다.

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

다른 API가 필요하면 args의 모듈 이름만 해당 모듈로 바꾸면 됩니다. 모듈별 정확한 이름과 환경변수는 서버 저장소의 README를 확인하세요.

한국 부동산 MCP (GitHub 클론)

git clone https://github.com/tae0y/real-estate-mcp
cd real-estate-mcp
npm install

인증키는 국토교통부 실거래가 공공데이터 신청 페이지에서 활용신청해 발급받고, 저장소 안내에 따라 .env 또는 환경변수로 주입합니다. 등록 방법은 위 uvx 예시와 동일하게 command/args에 실행 명령을 적으면 됩니다.

경로 B — 직접 MCP 서버 만들기

공개 서버에 없는 API를 붙이거나, 사내 인증·캐싱 정책을 직접 통제하려면 직접 개발합니다. 아래 예시는 Node.js 기반이며 Python SDK(mcp)도 동일한 개념을 따릅니다.

1단계 — 인증키 발급

data.go.kr에 회원가입합니다.
상단 검색창에 데이터셋 이름을 입력합니다(예: “아파트 매매 실거래가”).
결과에서 원하는 OpenAPI를 클릭하고 활용신청 버튼을 누릅니다.
승인 후 마이페이지 > 오픈API에서 일반 인증키(serviceKey) 를 복사합니다.

일반 공개 데이터는 신청 즉시 또는 영업일 1~2일 내에 승인됩니다. 활용신청한 데이터셋 페이지에는 엔드포인트 URL, 요청 변수, 응답 필드가 정리된 명세서가 첨부돼 있습니다. MCP 도구를 만들 때 이 명세서가 유일한 정답지이므로 먼저 내려받아 두세요.

2단계 — Node.js 환경 준비

mkdir my-openapi-mcp && cd my-openapi-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

Node.js 18 이상이 필요합니다(node --version으로 확인). Node 18+는 fetch가 전역으로 내장돼 있어 별도 HTTP 라이브러리 없이 바로 쓸 수 있습니다.

package.json에 ESM을 사용하도록 표시합니다.

{
  "type": "module"
}

3단계 — MCP 서버 코드 작성

McpServer 클래스와 server.tool()을 사용하면 도구 목록·실행 처리를 SDK가 알아서 라우팅해 주므로, 도구의 입력 스키마(zod)와 실행 함수만 정의하면 됩니다.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const API_KEY = process.env.DATA_GO_KR_API_KEY;

const server = new McpServer({
  name: "my-openapi-mcp",
  version: "0.1.0",
});

// 도구 등록: 이름 + zod 입력 스키마 + 실행 함수
server.tool(
  "search_public_data",
  {
    // 실제 요청 변수명은 데이터셋 명세서를 따르세요
    query: z.string().describe("검색어"),
  },
  async ({ query }) => {
    // 실제 엔드포인트·파라미터는 활용신청한 데이터셋 명세서 기준
    const url =
      `https://apis.data.go.kr/example` +
      `?serviceKey=${encodeURIComponent(API_KEY)}` +
      `&query=${encodeURIComponent(query)}` +
      `&type=json`;

    const res = await fetch(url);
    const data = await res.json();

    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

인증키 주의: 공공데이터포털이 발급하는 일반 인증키에는 URL에서 특수문자로 해석되는 문자(+, /, = 등)가 포함될 수 있습니다. 위 예시처럼 encodeURIComponent로 감싸 인코딩 오류를 예방하세요. 키는 코드에 하드코딩하지 말고 환경변수(env)로 주입합니다.

XML 응답 처리

공공데이터포털 API는 XML을 기본 반환하는 경우가 많습니다. &type=json을 지원하지 않는 API라면 fast-xml-parser로 변환합니다.

npm install fast-xml-parser

import { XMLParser } from "fast-xml-parser";

const parser = new XMLParser();
const text = await res.text();
const data = parser.parse(text);

응답 전체를 그대로 Claude에 넘기기보다, 명세서를 보고 필요한 필드만 추출해 반환하면 토큰을 아끼고 Claude가 더 정확히 답합니다. Python에서는 같은 역할을 xmltodict가 합니다.

4단계 — 로컬 실행 및 Claude Desktop 등록

node server.js

정상이면 출력 없이 stdio 입력 대기 상태가 됩니다(stdio 서버는 stdin/stdout으로 통신하므로 일반 콘솔 로그를 stdout에 찍으면 안 됩니다 — 디버그 출력은 stderr로 보내세요). Claude Desktop 설정 파일에 등록합니다.

{
  "mcpServers": {
    "my-openapi-mcp": {
      "command": "node",
      "args": ["/절대경로/my-openapi-mcp/server.js"],
      "env": {
        "DATA_GO_KR_API_KEY": "발급받은_인증키"
      }
    }
  }
}

args의 경로는 반드시 절대경로여야 합니다. 저장 후 Claude Desktop을 완전히 종료했다 재시작하면 서버가 연결됩니다.

5단계 — 동작 확인

Claude Desktop 채팅창의 도구 아이콘(망치 모양)을 누르면 등록된 도구 목록이 보입니다. 자연어로 질문하면 Claude가 search_public_data 도구를 자동으로 호출합니다. 도구가 보이지 않거나 호출이 실패하면, MCP Inspector로 서버를 단독 실행해 도구 목록과 응답을 먼저 검증하면 원인 분리가 쉽습니다.

흔한 오류와 해결

오류	원인	해결
`SERVICE_KEY_IS_NOT_REGISTERED_ERROR`	인증키 미입력·오타, 또는 미인코딩된 특수문자	`env` 주입 여부 확인, `encodeURIComponent` 적용
`LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR`	일일 호출 한도 초과	응답 캐싱 구현 또는 포털에서 한도 상향 신청
XML 파싱 오류(`SyntaxError`)	JSON을 기대했으나 XML 수신	`&type=json` 추가, 미지원 시 XML 파서 사용
도구가 Claude에 안 보임	설정 파일 경로·JSON 문법 오류	`claude_desktop_config.json` 문법 검증 후 재시작
`ENOENT: no such file or directory`	`server.js` 경로 오류	`args`의 절대경로 재확인

호출 한도와 캐싱

공공데이터포털 API는 보통 일일 호출 한도(예: 10,000~100,000건 등 데이터셋별로 상이)가 걸립니다. Claude가 비슷한 질문을 반복하면 같은 API를 여러 번 호출하기 쉬우므로, MCP 서버 내부에서 응답을 메모리나 SQLite에 캐시하고 동일 요청이면 캐시를 우선 반환하도록 구현하면 실제 호출 수를 크게 줄일 수 있습니다. 정확한 한도는 활용신청한 데이터셋 페이지에서 확인하세요.

공개 서버 vs. 직접 개발

항목	공개 서버	직접 개발
시작 속도	빠름(수 분)	느림(수 시간~)
커스터마이징	제한적	완전 자유
유지보수	커뮤니티 의존	자체 책임
특수 요구사항	어려움	가능

범용 공공 API는 공개 서버를 먼저 검토하고, 사내 전용 API나 인증·캐싱이 복잡한 경우 직접 개발하는 것이 효율적입니다.

자주 묻는 질문

공공데이터포털 인증키는 어떻게 발급받나요?

data.go.kr에 회원가입한 뒤 원하는 데이터셋 페이지에서 ‘활용신청’을 클릭하면 됩니다. 일반 공개 API는 신청 즉시 또는 1~2일 내 승인되며, 마이페이지 > 오픈API에서 인증키를 확인합니다.

직접 만들지 않고 기존 서버를 쓸 수 있나요?

네. real-estate-mcp나 data-go-mcp-servers처럼 공개된 서버를 GitHub에서 클론하거나 uvx로 설치한 뒤 인증키만 넣으면 바로 사용할 수 있습니다.

브라우저에서는 CORS로 직접 호출이 안 되는데 MCP는 괜찮나요?

MCP 서버는 서버사이드(Node.js·Python 프로세스)에서 API를 호출하므로 브라우저 CORS와 무관합니다. Claude가 stdio로 MCP 서버를 호출하고, 서버가 대신 공공 API에 HTTP 요청을 보내는 구조입니다.

API 응답이 XML이면 어떻게 처리하나요?

&type=json을 지원하면 그것을 쓰고, 아니면 Node.js는 fast-xml-parser, Python은 xmltodict로 변환한 뒤 필요한 필드만 추출해 Claude에 반환합니다.

Claude Code(CLI)와 Claude Desktop 양쪽에서 쓸 수 있나요?

네. stdio 방식 MCP 서버는 Claude Desktop의 claude_desktop_config.json 또는 Claude Code CLI 설정에 등록하면 두 클라이언트에서 동일하게 동작합니다.

호출 한도가 걱정됩니다.

데이터셋별 일일 한도가 있으므로, MCP 서버에서 응답을 메모리·SQLite에 캐시하고 동일 요청에 캐시를 우선 반환하도록 구현하면 실제 호출 수를 줄일 수 있습니다.

다음 단계

한국 부동산 MCP — 아파트 실거래가를 Claude로 바로 조회
공공데이터포털 MCP 서버 모음 — 사업자등록·조달청·금감원 API 통합 사용
표준국어대사전 MCP — 국립국어원 API를 로컬 SQLite로 오프라인 활용
공공데이터 카테고리 전체 보기 — data.go.kr 연동 MCP 서버 목록
모든 MCP 서버 보기 — 금융·의료·교통 등 한국 API MCP 탐색
MCP 서버 직접 등록하기 — 직접 만든 공공데이터 MCP 서버를 MCP모아에 공유