공공데이터 OpenAPI MCP 서버 만들기 — 한국 공공 API를 Claude에 연결

한국 공공데이터포털(data.go.kr)에서 제공하는 수천 개의 OpenAPI를 Claude에 직접 연결할 수 있습니다. MCP(Model Context Protocol) 서버를 중간에 두면, Claude가 “이 사업자 번호가 유효한지 확인해 줘” 또는 “이 아파트 최근 실거래가 알려 줘”처럼 자연어로 요청할 때 실시간 공공 데이터를 조회해 답합니다. 이 글에서는 공공데이터 OpenAPI MCP 서버를 직접 만드는 방법과, 이미 공개된 서버를 즉시 활용하는 방법을 모두 다룹니다.

왜 공공데이터 OpenAPI를 MCP로 연결해야 할까요

Claude는 2024년 학습 마감 이후의 실시간 정보를 알지 못합니다. 오늘의 아파트 실거래가, 방금 신청된 사업자등록 상태, 최신 조달청 입찰 공고는 Claude의 파라미터 안에 없습니다. MCP 서버는 이 간극을 메우는 표준 인터페이스입니다.

공공데이터포털에는 행정·교통·의료·환경·금융 등 60,000개 이상의 데이터셋이 있으며 대부분 무료입니다. MCP로 한 번 연결해 두면 Claude가 필요할 때마다 해당 API를 호출하고, 결과를 이해하고, 사용자 질문에 맞춰 분석해 줍니다.

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

이미 만들어진 공개 MCP 서버로 빠르게 시작하기

직접 개발하기 전에 오픈소스로 공개된 서버를 먼저 살펴보는 것이 좋습니다. 아래 두 서버는 data.go.kr 기반 MCP 서버 중 국내에서 대표적으로 활용되는 사례입니다.

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

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

data-go-mcp-servers는 국민연금공단 사업장 가입 조회, 국세청 사업자등록 진위 확인, 조달청 나라장터, 금융감독원 기업재무정보 등 여러 API를 모듈별로 제공합니다.

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

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

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

한국 부동산 MCP 설치 (GitHub 클론)

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

API 키는 국토교통부 실거래가 공공데이터 신청 페이지에서 발급받아 .env 파일 또는 환경변수로 주입합니다.

단계별: 공공데이터 OpenAPI MCP 서버 직접 만들기

특정 API를 커스텀하게 연결하거나 사내에서 운영하려면 직접 개발이 필요합니다. 아래 예시는 Node.js 기반이며, Python SDK도 동일한 개념을 따릅니다.

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

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

일반 공개 데이터는 신청 즉시 또는 영업일 1~2일 내에 승인됩니다.

2단계 — Node.js 환경 준비

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

Node.js 18 이상이 필요합니다. node --version으로 확인하세요.

3단계 — MCP 서버 코드 작성

아래는 공공 API를 하나의 MCP 도구로 등록하는 최소 예시입니다. (실제 API 엔드포인트와 파라미터는 활용신청한 데이터셋의 명세서를 참고하세요.)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import fetch from "node-fetch";

const API_KEY = process.env.DATA_GO_KR_API_KEY;

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

// 도구 목록 반환
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_public_data",
      description: "공공데이터포털 API를 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "검색어" }
        },
        required: ["query"]
      }
    }
  ]
}));

// 도구 실행
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "search_public_data") {
    const query = request.params.arguments.query;
    // 실제 API 엔드포인트는 데이터셋 명세서를 참고하세요
    const url = `https://apis.data.go.kr/example?serviceKey=${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) }]
    };
  }
  throw new Error("Unknown tool");
});

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

XML 응답을 반환하는 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);

4단계 — 로컬 실행 및 Claude Desktop 연결

node server.js

정상이면 stdio 상태로 대기합니다. Claude Desktop 설정 파일에 등록합니다.

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

설정 저장 후 Claude Desktop을 재시작하면 MCP 서버가 연결됩니다.

5단계 — 동작 확인

Claude Desktop 채팅창에서 도구 아이콘(망치 모양)을 클릭하면 등록된 도구 목록을 확인할 수 있습니다. 자연어로 질문하면 Claude가 MCP 도구를 자동으로 호출합니다.

흔한 오류와 해결 방법

오류	원인	해결 방법
SERVICE_KEY_IS_NOT_REGISTERED_ERROR	API 키 미입력 또는 오타	환경변수 주입 여부와 키 값 재확인
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의 절대경로 확인

공개 서버 vs. 직접 개발 비교

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

팀 내부 전용 API나 인증이 복잡한 시스템은 직접 개발이 낫고, 범용 공공 API는 공개 서버를 먼저 검토하는 것이 효율적입니다.

자주 묻는 질문

공공데이터포털 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로 연결하는 방법을 이해했다면, 다음 단계를 시도해 보세요.

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