공공 API MCP 서버 만드는 법 — 한국 공공데이터를 AI 도구로 래핑하기

한국 공공데이터포털(data.go.kr)에는 부동산 실거래가, 날씨, 법령, 사업자등록 진위 등 수천 개의 무료 API가 있습니다. 이 API를 MCP 서버로 래핑하면 Claude가 직접 공공데이터를 조회하고 분석할 수 있는 AI 도구가 됩니다. 이 글에서는 Python으로 공공 API MCP 서버를 처음부터 만드는 전 과정을 단계별로 안내합니다. 별도 인프라 없이 로컬에서 Claude Desktop과 연결하는 것을 목표로 합니다.

왜 공공 API를 MCP 서버로 만드나요?

Claude 같은 LLM은 기본적으로 인터넷에 실시간으로 접근할 수 없습니다. MCP(Model Context Protocol)는 외부 데이터 소스나 도구를 표준화된 방식으로 LLM에 연결하는 프로토콜입니다. 공공 API를 MCP 서버로 래핑하면 다음 흐름이 가능해집니다.

사용자 질문
    ↓
Claude (LLM)
    ↓  MCP 도구 호출 (stdio)
MCP 서버 (Python)
    ↓  HTTP 요청
data.go.kr 공공 API
    ↓  JSON/XML 응답
MCP 서버 (파싱 · 가공)
    ↓  도구 결과 반환
Claude → 사용자에게 답변

직접 개발 시 얻는 이점은 다음과 같습니다.

구분	직접 MCP 서버 개발	기존 챗봇 플러그인
데이터 범위	data.go.kr 전체 API 선택 가능	플러그인이 지원하는 것만
응답 가공	자유롭게 포맷·필터링	정해진 스키마
비용	공공데이터는 무료	유료 API 사용 시 과금
유지보수	직접 관리	제공자 의존

준비물

• Python 3.10 이상 (3.11 권장)
• uv 또는 pip (패키지 관리)
• 공공데이터포털 API 인증키 (data.go.kr 무료 발급)
• Claude Desktop (MCP 클라이언트로 사용)

단계별 공공 API MCP 서버 개발

1단계: data.go.kr API 키 발급

data.go.kr에 로그인한 뒤, 사용하고 싶은 API 서비스 페이지로 이동해 ‘활용신청’ 버튼을 누릅니다. 목적 설명을 간단히 작성하면 대부분 즉시 인증키가 발급됩니다.

발급된 키는 두 종류입니다.

• 일반 인증키: URL 인코딩 필요(퍼센트 인코딩된 문자열)
• UTF-8 인증키: 그대로 사용 가능

이 가이드에서는 UTF-8 인증키를 사용합니다. 발급된 키는 환경 변수로 관리하는 것이 보안상 안전합니다.

2단계: Python 환경 및 의존성 설치

# uv를 사용하는 경우 (권장)
uv init public-api-mcp
cd public-api-mcp
uv add mcp httpx python-dotenv

# pip를 사용하는 경우
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install mcp httpx python-dotenv

프로젝트 루트에 .env 파일을 만들어 API 키를 저장합니다.

# .env
PUBLIC_DATA_API_KEY=여기에_발급받은_UTF8_인증키_입력

3단계: MCP 서버 기본 골격 작성

server.py 파일을 생성합니다.

# server.py
import os
import asyncio
import httpx
from dotenv import load_dotenv
from mcp.server.fastmcp import FastMCP

load_dotenv()

API_KEY = os.getenv("PUBLIC_DATA_API_KEY", "")
BASE_URL = "https://apis.data.go.kr"

mcp = FastMCP("공공데이터 MCP 서버")

FastMCP는 Anthropic의 공식 Python MCP SDK에 포함된 고수준 헬퍼 클래스입니다. @mcp.tool() 데코레이터만 붙이면 함수가 자동으로 MCP 도구로 등록됩니다.

4단계: 공공 API 호출 도구 구현

예시로 국세청 사업자등록 진위 확인 API를 도구로 노출해 보겠습니다. 실제 엔드포인트와 파라미터는 data.go.kr 해당 서비스 문서를 기준으로 맞춰야 합니다.

# server.py (이어서)

@mcp.tool()
async def check_business_registration(business_number: str) -> dict:
    """
    국세청 사업자등록 진위 확인 API를 조회합니다.
    business_number: 하이픈 없이 10자리 사업자등록번호 (예: 1234567890)
    """
    endpoint = "/nts-businessman/v1/status"
    params = {
        "serviceKey": API_KEY,
        "b_no": business_number,
    }
    async with httpx.AsyncClient(timeout=10.0) as client:
        response = await client.get(BASE_URL + endpoint, params=params)
        response.raise_for_status()
        data = response.json()
    return data


if __name__ == "__main__":
    mcp.run(transport="stdio")

XML을 반환하는 API라면 아래처럼 파싱합니다.

import xml.etree.ElementTree as ET

# response.text가 XML일 때
root = ET.fromstring(response.text)
items = root.findall(".//item")
result = []
for item in items:
    row = {child.tag: child.text for child in item}
    result.append(row)
return result

5단계: Claude Desktop에 서버 등록

Claude Desktop의 설정 파일을 열어 서버를 추가합니다.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "public-api-mcp": {
      "command": "python",
      "args": ["/절대경로/public-api-mcp/server.py"],
      "env": {
        "PUBLIC_DATA_API_KEY": "여기에_인증키_입력"
      }
    }
  }
}

uv를 사용했다면 command를 "uv", args를 ["run", "python", "server.py"]로 바꾸고 cwd에 프로젝트 경로를 지정합니다.

{
  "mcpServers": {
    "public-api-mcp": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/절대경로/public-api-mcp",
      "env": {
        "PUBLIC_DATA_API_KEY": "여기에_인증키_입력"
      }
    }
  }
}

6단계: 동작 확인

Claude Desktop을 완전히 종료했다가 다시 실행합니다. 채팅창 하단에 도구 아이콘(망치 모양)이 나타나면 서버가 정상 연결된 것입니다. 다음처럼 질문해 봅니다.

“사업자등록번호 1234567890이 유효한지 확인해줘.”

Claude가 check_business_registration 도구를 호출해 공공데이터 API 결과를 바탕으로 답변합니다.

흔한 오류와 해결법

오류 메시지	원인	해결 방법
SERVICE_KEY_IS_NOT_REGISTERED_ERROR	API 키 오류 또는 URL 인코딩 문제	UTF-8 인증키 사용, 공백·특수문자 주의
NORMAL_SERVICE_ERROR	호출 한도 초과 또는 잘못된 파라미터	data.go.kr 마이페이지에서 호출량 확인
Connection refused (Claude Desktop)	서버 경로 오류 또는 Python 미설치	command 경로를 절대 경로로, python --version 확인
ModuleNotFoundError: mcp	가상환경 미활성화	cwd와 command가 같은 venv를 바라보도록 수정
XML 파싱 오류	BOM(UTF-8-sig) 또는 인코딩 문제	response.content에 ET.fromstring() 직접 적용

이미 만들어진 한국 공공데이터 MCP 서버

직접 개발하기 전에 오픈소스로 공개된 서버를 먼저 살펴보는 것도 좋습니다. 구조를 참고하거나 그대로 사용할 수 있습니다.

• 한국 부동산 MCP: 국토교통부 실거래가 API로 아파트·오피스텔 실거래 조회 및 매수 시나리오 분석. GitHub: tae0y/real-estate-mcp
• 공공데이터포털 MCP 서버 모음: 국민연금·국세청·조달청·금융감독원 등 여러 공공 API를 묶은 서버. uvx data-go-mcp.nps-business-enrollment@latest 로 즉시 실행 가능. GitHub: Koomook/data-go-mcp-servers
• 표준국어대사전 MCP 서버: 국립국어원 사전을 로컬 SQLite로 변환해 오프라인 검색. GitHub: dahlia/ko-stdict-mcp

공공데이터 카테고리 전체 서버 목록에서 더 많은 서버를 확인할 수 있습니다.

서버 품질을 높이는 팁

1. 도구 설명(docstring)을 구체적으로 작성하세요. Claude는 도구를 선택할 때 docstring을 참고합니다. “사업자등록번호를 확인합니다” 보다 “10자리 사업자등록번호를 입력받아 국세청 API로 진위와 영업 상태를 확인합니다”가 훨씬 잘 선택됩니다.

2. 응답 크기를 제한하세요. 공공 API는 수백 건의 결과를 한 번에 반환하기도 합니다. numOfRows=10 같은 파라미터로 건수를 제한하거나, 도구 함수 안에서 슬라이싱해 Claude의 컨텍스트 낭비를 줄이세요.

3. 결과를 로컬에 캐시하세요. 같은 데이터를 반복 조회하는 경우 SQLite에 캐시를 저장하면 API 호출 한도를 아낄 수 있습니다. 표준국어대사전 MCP 서버가 이 방식을 잘 구현한 사례입니다.

4. 타입 힌트를 반드시 붙이세요. FastMCP는 함수 시그니처의 타입 힌트로 MCP 도구 스키마를 자동 생성합니다. 타입이 없으면 Claude가 파라미터를 잘못 추론할 수 있습니다.

자주 묻는 질문

공공데이터 API 키는 어디서 발급받나요? 공공데이터포털(data.go.kr)에 회원가입 후, 원하는 API 서비스 페이지에서 ‘활용신청’ 버튼을 누르면 됩니다. 심사 없이 즉시 발급되는 API가 대부분이며, 일부는 기관 검토 후 1~3일이 걸립니다.

Python 말고 다른 언어로도 MCP 서버를 만들 수 있나요? 네, Anthropic이 공식 SDK를 TypeScript(Node.js)와 Python 두 가지로 제공합니다. 공공 API 연동은 HTTP 호출만 가능하면 어떤 런타임이든 사용할 수 있습니다.

stdio 방식과 SSE(HTTP) 방식 중 어느 것을 선택해야 하나요? 로컬에서 Claude Desktop과 단독으로 연동할 때는 stdio가 가장 간단합니다. 여러 클라이언트가 동시에 접속하거나 원격 배포가 필요한 경우에는 SSE(Streamable HTTP) 방식을 고려하세요.

공공데이터 응답이 XML 형태인데 어떻게 처리하나요? Python 표준 라이브러리 xml.etree.ElementTree 또는 xmltodict 패키지로 XML을 파싱한 뒤 딕셔너리로 변환하고, 도구 반환값은 JSON 직렬화 가능한 형태로 가공하면 됩니다.

이미 만들어진 한국 공공데이터 MCP 서버는 없나요? 있습니다. 국토교통부 실거래가 데이터를 다루는 한국 부동산 MCP, 여러 공공 API를 묶은 공공데이터포털 MCP 서버 모음 등이 오픈소스로 공개되어 있습니다. 직접 개발 전에 참고하거나 그대로 사용할 수 있습니다.

API 일일 호출 한도를 초과하면 어떻게 되나요? 공공데이터포털 API는 대부분 하루 1,000~10,000건 한도가 있으며, 초과 시 오류 코드를 반환합니다. 프로덕션 용도라면 결과를 로컬 캐시(SQLite 등)에 저장해 불필요한 중복 호출을 줄이는 것을 권장합니다.

다음 단계

이 가이드의 구조를 이해했다면 어떤 공공 API든 같은 방식으로 MCP 서버로 만들 수 있습니다. 공공데이터 카테고리에서 다른 개발자들이 공개한 서버를 탐색해 보세요. 직접 만든 서버가 있다면 MCP모아에 등록해 커뮤니티와 함께 사용할 수도 있습니다. 더 많은 MCP 서버는 전체 서버 목록에서 확인하실 수 있습니다.