data.go.kr에서 API 키를 발급받았는데 MCP 서버 실행 시 '인증 오류'가 납니다. 왜 그런가요?

가장 흔한 원인은 인코딩된 키(URL-encoded key)를 그대로 설정 파일에 붙여넣는 것입니다. data.go.kr 마이페이지에서는 인코딩 키와 디코딩 키 두 가지를 제공합니다. 대부분의 MCP 서버는 디코딩 키(일반 텍스트, '%2B' 같은 퍼센트 인코딩이 없는 형태)를 사용합니다. 또한 API 활용 신청이 '승인' 상태인지, 활용 기간이 유효한지도 함께 확인하세요.

Claude Desktop에서 MCP 서버가 목록에 나타나지 않습니다. 설정 파일은 어디에 있나요?

Claude Desktop의 MCP 설정 파일은 macOS 기준 '~/Library/Application Support/Claude/claude_desktop_config.json', Windows 기준 '%APPDATA%\Claude\claude_desktop_config.json'에 있습니다. 파일을 수정한 뒤 Claude Desktop을 완전히 종료(트레이 아이콘 우클릭 → 종료)하고 재시작해야 변경 사항이 반영됩니다.

uvx 명령어로 공공데이터 MCP 서버를 실행하면 'command not found' 오류가 납니다.

uvx는 Python 패키지 실행 도구인 uv의 일부입니다. 'curl -LsSf https://astral.sh/uv/install.sh | sh' 명령으로 uv를 먼저 설치하세요. 설치 후 새 터미널을 열어 'uvx --version'으로 정상 설치를 확인합니다. macOS라면 Homebrew로 'brew install uv'도 가능합니다.

API 호출은 성공하는데 AI가 엉뚱한 답변을 합니다. MCP 서버 문제인가요?

MCP 서버가 API 응답을 정상적으로 반환하더라도, AI 모델이 응답 구조를 잘못 해석하거나 한국어 필드명을 잘못 읽는 경우가 있습니다. 먼저 Claude나 사용 중인 AI의 대화 내에서 '방금 공공데이터 API에서 받은 원본 응답을 그대로 보여줘'라고 요청해 응답 자체를 확인하세요. 원본 데이터가 맞게 나온다면 AI의 해석 문제이므로, 질문을 더 구체적으로 바꾸거나 필드명을 명시하면 개선됩니다.

일일 호출 한도를 초과했습니다. 어떻게 해결하나요?

data.go.kr 개발계정은 API별로 일일 최대 호출 건수가 정해져 있습니다(보통 1,000~10,000건). 한도 초과 시 다음 날 자정 이후 리셋됩니다. 지속적으로 한도가 부족하다면 data.go.kr 마이페이지에서 '운영계정 전환 신청'을 하거나, 해당 API의 상세 페이지에서 트래픽 한도 증가를 요청할 수 있습니다.

공공데이터 MCP 서버를 여러 개 동시에 사용할 수 있나요?

네, 가능합니다. claude_desktop_config.json의 'mcpServers' 객체 안에 서버를 여러 개 등록하면 됩니다. 각 서버에 다른 키 이름을 부여하면 AI가 적절한 서버를 골라 사용합니다. 다만 각 서버가 서로 다른 API 키를 요구할 수 있으므로, 각각 별도로 발급해야 합니다.

공공데이터 MCP 자주 묻는 질문 — API 키 오류·설정 문제 해결 Q&A

한국 공공데이터 MCP 연동에서 가장 많이 겪는 문제는 API 키 형식 오류와 설정 파일 위치 혼동입니다. data.go.kr에서 발급받은 인코딩 키를 그대로 붙여넣거나, 설정 파일 저장 후 AI 클라이언트를 재시작하지 않으면 MCP 서버가 작동하지 않습니다. 이 글은 실제로 자주 접수되는 질문을 모아 원인과 해결 방법을 명확하게 정리합니다.

공공데이터 MCP란 무엇이며 왜 오류가 자주 생기나요?

공공데이터 MCP 서버는 한국 공공데이터포털(data.go.kr)의 OpenAPI를 Claude, Cursor 등 AI 도구에서 직접 호출할 수 있게 연결해 주는 중간 서버입니다. AI가 “이번 달 아파트 실거래가 조회해줘”라는 요청을 받으면 MCP 서버를 통해 공공 API를 자동으로 호출하고 결과를 정리해 줍니다.

오류가 자주 생기는 이유는 세 가지입니다.

원인	빈도	증상
API 키 형식 오류 (인코딩/디코딩 혼용)	매우 높음	인증 실패, 401/403 오류
설정 파일 경로 혼동 또는 재시작 누락	높음	서버가 목록에 안 뜸
API 활용 신청 미승인 또는 기간 만료	중간	요청 시 오류 반환
일일 호출 한도 초과	중간	특정 시간대 이후 실패
uv/uvx/npx 미설치	낮음	command not found

각 문제의 해결 방법을 아래에서 하나씩 살펴보겠습니다.

자주 묻는 질문

data.go.kr API 키 오류 — ‘인증 실패’ 또는 SERVICE_KEY_IS_NOT_REGISTERED_ERROR

원인: data.go.kr 마이페이지에는 같은 키가 두 형태로 표시됩니다.

인코딩 키: URL 인코딩된 형태. %2B, %3D 같은 퍼센트 기호 포함.
디코딩 키: 일반 텍스트 형태. +, /, = 같은 문자가 그대로 표시.

대부분의 MCP 서버 및 HTTP 라이브러리는 디코딩 키를 사용합니다. 인코딩 키를 env에 넣으면 서버가 키를 이중 인코딩해 API가 알아보지 못합니다.

해결 방법:

data.go.kr 마이페이지 → 오픈API → 개발계정 → 인증키 정보 이동
“일반 인증키(디코딩)” 탭을 선택해 복사
설정 파일의 env 항목에 붙여넣기

{
  "mcpServers": {
    "data-go-mcp": {
      "command": "uvx",
      "args": ["data-go-mcp.nps-business-enrollment@latest"],
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_디코딩_키_붙여넣기"
      }
    }
  }
}

추가로 확인할 사항:

API 활용 신청 상태가 “승인” 인지 확인 (신청 후 수분~수시간 소요되는 API도 있음)
활용 기간이 만료되지 않았는지 확인 (기본 2년, 연장 가능)
해당 API의 서비스 엔드포인트가 운영 서버 URL인지 확인 (개발 URL과 다름)

Claude Desktop에서 MCP 서버가 목록에 나타나지 않는 경우

MCP 서버 설정은 클라이언트마다 파일 위치가 다릅니다.

Claude Desktop 설정 파일 위치
├── macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
├── Windows: %APPDATA%\Claude\claude_desktop_config.json
└── Linux:   ~/.config/Claude/claude_desktop_config.json

체크리스트:

파일을 저장했는지 확인 (편집기에서 Cmd+S 또는 Ctrl+S)
JSON 문법 오류 없는지 확인 — 중괄호/쉼표 누락이 잦음
Claude Desktop을 완전히 종료 후 재시작 (트레이 아이콘 우클릭 → Quit)
재시작 후 Claude 대화창에서 도구 아이콘(망치 모양)을 클릭해 등록된 서버 확인

JSON 문법을 간단히 검증하려면 터미널에서 다음 명령을 실행하세요.

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

오류가 없으면 파싱 결과가 그대로 출력됩니다. 문법 오류가 있으면 어느 줄에서 발생했는지 알려줍니다.

uvx 명령어가 없다는 오류 (command not found: uvx)

공공데이터포털 MCP 서버 모음(data-go-mcp-servers)을 비롯한 일부 서버는 Python 생태계의 uvx 명령으로 실행합니다. uvx는 uv 패키지 매니저에 포함된 도구입니다.

설치 방법:

macOS / Linux:

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

macOS (Homebrew):

brew install uv

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 새 터미널을 열어 경로를 인식시킨 뒤 확인합니다.

uvx --version

정상이면 버전 번호가 출력됩니다. 그 후 MCP 서버를 다시 시작하면 됩니다.

API 호출은 성공하는데 AI 답변이 틀리는 경우

MCP 서버가 정상적으로 공공 API를 호출해도 AI 모델이 응답을 잘못 해석하는 경우가 있습니다. 데이터 흐름을 정리하면 다음과 같습니다.

사용자 질문
    ↓
AI 모델 (Claude 등)
    ↓  MCP 도구 호출 요청
MCP 서버 (로컬 프로세스)
    ↓  HTTP 요청 + API 키
공공 API (data.go.kr 등)
    ↓  JSON 응답
MCP 서버
    ↓  파싱된 결과 반환
AI 모델
    ↓  자연어로 해석·요약
사용자에게 최종 답변

어디서 문제가 생겼는지 확인하려면, 대화에서 “방금 공공데이터 API에서 받은 원본 응답을 그대로 보여줘”라고 요청하세요. 원본 데이터가 정확하다면 AI의 해석 단계 문제이므로, 질문을 더 구체적으로 (“2025년 1월 서울 강남구 아파트 실거래가를 면적 오름차순으로 보여줘”) 바꾸면 대부분 해결됩니다.

일일 호출 한도(트래픽 초과) 오류

data.go.kr 개발계정은 API별로 일일 최대 호출 건수가 제한됩니다. 한도 초과 시 LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR 오류가 반환됩니다.

계정 유형	일반 한도	해결책
개발계정	API별 상이 (보통 1,000~10,000건)	익일 자정 후 자동 리셋
운영계정	요청 한도 대폭 상향	마이페이지에서 전환 신청

단기 해결: 다음 날까지 기다리거나, 다른 API 키로 전환. 장기 해결: data.go.kr 마이페이지 → 오픈API → 운영계정 전환 신청. 운영 목적과 예상 트래픽을 기재하면 수일 내 승인됩니다.

여러 공공데이터 MCP 서버를 동시에 사용하는 방법

설정 파일의 mcpServers 안에 이름을 달리 해 서버를 나열하면 됩니다.

{
  "mcpServers": {
    "real-estate": {
      "command": "npx",
      "args": ["-y", "real-estate-mcp"],
      "env": {
        "MOLIT_API_KEY": "국토교통부_API_키"
      }
    },
    "nps-business": {
      "command": "uvx",
      "args": ["data-go-mcp.nps-business-enrollment@latest"],
      "env": {
        "DATA_GO_KR_API_KEY": "공공데이터포털_API_키"
      }
    }
  }
}

각 서버마다 별도의 API 키를 발급받아야 한다는 점을 기억하세요. 한국 부동산 MCP(real-estate-mcp)는 국토교통부 실거래가 API 키를, 공공데이터포털 MCP 서버 모음(data-go-mcp-servers)은 data.go.kr 통합 키를 각각 요구합니다.

공공데이터 API 키 발급 요약 흐름

아직 API 키를 발급받지 않았다면 아래 순서를 따르세요.

1. data.go.kr 접속 → 회원가입 · 로그인
2. 원하는 API 검색 (예: "국토교통부 아파트 실거래가")
3. API 상세 페이지 → [활용신청] 클릭
4. 활용 목적 입력 → 신청 완료 (대부분 즉시 또는 당일 승인)
5. 마이페이지 → 오픈API → 개발계정 → "일반 인증키(디코딩)" 복사
6. MCP 설정 파일 env에 붙여넣기 → 클라이언트 재시작

추가로 살펴볼 리소스

공공데이터 카테고리 전체 MCP 서버 목록 — 현재 등록된 공공데이터 관련 MCP 서버를 한눈에 확인하세요.
표준국어대사전 MCP 서버 — API 키 없이 바로 사용할 수 있는 국립국어원 표준국어대사전 MCP입니다. 공공데이터 MCP의 진입 장벽 없이 시작하기 좋습니다.
MCP 서버 전체 목록 보기 — 더 다양한 한국 MCP 서버를 찾아보세요.
가이드 전체 목록 — 설치·설정·활용 가이드 모음.

공공데이터 MCP를 쓰다가 이 글에서 다루지 않은 문제를 발견하셨다면, MCP모아에 서버 또는 문제를 제보해 주시면 다음 글에 반영하겠습니다.