M MCP모아
튜토리얼 · 2026.06.20 업데이트

기상청 단기예보 MCP 서버 — Claude에서 실시간 날씨 조회하기

기상청 단기예보 API를 Korea Weather MCP 서버로 연결해 Claude에서 자연어로 날씨를 조회합니다. Smithery CLI 설치, 디코딩 키 발급, 인증 오류 해결까지 실전 위주로 정리했습니다.

기상청 단기예보 API와 Claude AI가 MCP 서버로 연결되는 데이터 흐름을 보여주는 표지 이미지

기상청 단기예보 MCP 서버를 연결하면 Claude 같은 AI 클라이언트에서 “내일 부산 날씨 어때?”, “이번 주 서울 강수 확률 알려줘” 같은 질문에 실시간 예보로 답할 수 있습니다. 직접 서버를 만들 필요는 없습니다. 이미 공개된 Korea Weather MCP 서버를 Smithery CLI 한 줄로 Claude Desktop에 등록하고, data.go.kr에서 발급받은 API 키를 연결하면 됩니다. 설치부터 첫 테스트까지 대략 5분이면 끝납니다.

이 가이드는 서버 코드를 작성하는 글이 아니라, 기존 서버를 설치·연결하고 실패 지점을 빠르게 잡아내는 데 초점을 둡니다.

왜 별도의 날씨 MCP 서버가 필요한가

대형 언어 모델은 훈련 시점까지의 데이터만 알기 때문에 “오늘 날씨”처럼 실시간 정보를 묻는 질문에는 정확히 답하지 못합니다. 웹 검색 도구를 붙여도 기상 데이터를 정형화된 형태로 안정적으로 끌어오기는 어렵습니다.

기상청이 공공데이터포털(data.go.kr)을 통해 제공하는 단기예보 API는 전국을 격자(nx, ny)로 나눠 기온·강수확률·하늘상태 등을 무료로 제공합니다. 이 API를 MCP 서버로 감싸면 AI가 도구(Tool) 형태로 직접 호출할 수 있고, 사용자는 별도 앱 없이 대화창 하나로 날씨를 확인할 수 있습니다.

사용자 질문
    │
    ▼
Claude / AI 클라이언트
    │  MCP 프로토콜
    ▼
Korea Weather MCP 서버 (ohhan777/korea_weather)
    │  HTTP 요청 + KMA_API_KEY
    ▼
기상청 단기예보 조회서비스 (data.go.kr)
    │  JSON 응답 (TMP, POP, SKY ...)
    ▼
MCP 서버 → Claude → 자연어 답변

응답에 담기는 TMP(기온), POP(강수확률), SKY(하늘상태) 같은 카테고리 코드의 의미가 궁금하다면 기상청 단기예보 카테고리 코드 해석표를 참고하세요. MCP 서버가 코드를 자연어로 풀어주지만, 응답을 직접 검증할 때 유용합니다.

준비물 한눈에 보기

항목필요 여부확인 방법 / 비고
Node.js 18 이상 (npx 포함)필수node -v, npx --version
Claude Desktop필수최신 버전 권장
data.go.kr 계정필수무료 회원가입
기상청 단기예보 API 키 (디코딩)필수활용 신청 후 발급, 아래 1단계
인터넷 연결필수API 실시간 호출

Node.js가 없다면 nodejs.org에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 npx --version으로 동작을 확인하세요.

단계별 설치

1단계. data.go.kr에서 기상청 API 키 발급

  1. 기상청_단기예보 조회서비스 페이지에 로그인합니다.
  2. 우측 상단 활용신청 버튼을 클릭하고 활용 목적을 간단히 입력합니다.
  3. 승인은 즉시 또는 최대 1~2일 내에 완료됩니다.
  4. 마이페이지 → 오픈API → 개발계정에서 해당 API의 일반 인증키(디코딩) 값을 복사합니다.

반드시 디코딩 키를 사용하세요. 인코딩 키(%2B, %2F 같은 퍼센트 인코딩 문자가 포함된 형태)를 그대로 넣으면 인증 오류가 납니다. 이것이 가장 흔한 실패 원인입니다.

2단계. Korea Weather MCP 서버 등록

터미널(macOS: 터미널, Windows: PowerShell 또는 명령 프롬프트)에서 아래 명령을 실행합니다.

npx -y @smithery/cli mcp add ohhan777/korea_weather --client claude

이 명령은 Smithery CLI를 통해 Korea Weather MCP 서버를 Claude Desktop 설정 파일에 자동 등록합니다. 실행 중 API 키를 묻는 프롬프트가 나타나면 1단계에서 복사한 디코딩 키를 붙여넣습니다.

3단계. 설정 파일에서 API 키 확인

Smithery CLI가 설정 파일을 자동으로 수정하지만, 직접 확인하거나 편집하려면 아래 경로를 엽니다.

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

서버가 다음과 같이 등록돼 있어야 합니다.

{
  "mcpServers": {
    "korea_weather": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "ohhan777/korea_weather"],
      "env": {
        "KMA_API_KEY": "여기에_발급받은_디코딩_인증키_입력"
      }
    }
  }
}

KMA_API_KEY 값이 디코딩 키로 올바르게 들어갔는지 확인합니다.

4단계. Claude Desktop 재시작 및 동작 확인

설정 변경은 Claude Desktop을 완전히 종료한 뒤 다시 실행해야 반영됩니다. 단순히 창을 닫는 것으로는 부족합니다.

  • macOS: 메뉴바 Claude 아이콘 우클릭 → 종료(Quit)
  • Windows: 작업 표시줄 트레이 아이콘 우클릭 → 종료

재시작 후 대화창에 아래 질문을 입력해 테스트합니다.

오늘 서울 날씨 알려줘
내일 부산 날씨와 강수 확률은?
이번 주 대구 최고 기온 예보 알려줘

응답에 기온, 강수 확률, 하늘상태 등이 포함되면 정상 작동입니다.

흔한 오류와 해결 방법

”인증키가 유효하지 않습니다” 오류

원인은 거의 두 가지입니다.

  1. 인코딩 키 사용 — %2B, %2F 같은 문자가 보이면 인코딩 키입니다. 마이페이지에서 일반 인증키(디코딩) 탭의 값을 다시 복사하세요.
  2. 활용 신청 미승인 — 마이페이지에서 해당 API의 활용 상태가 ‘승인’인지 확인하세요.

Claude Desktop에 서버가 안 뜨는 경우

claude_desktop_config.json은 JSON이므로 쉼표나 중괄호 누락 같은 사소한 문법 오류 하나로 전체 파일이 무효화됩니다. 온라인 JSON 유효성 검사 도구로 문법을 점검하고, mcpServers 항목이 올바르게 들어갔는지 확인한 뒤 Claude Desktop을 완전히 재시작하세요.

”npx: command not found” 오류

Node.js가 설치되지 않았거나 PATH에 등록되지 않은 경우입니다. node -v로 설치를 확인하고, 없으면 nodejs.org에서 설치한 뒤 터미널을 새로 열어야 PATH가 적용됩니다.

호출 한도 초과

data.go.kr 개발계정은 API별 일일 호출 한도가 있습니다. 한도를 넘으면 오류 코드가 반환되며 당일 자정 이후 초기화됩니다. 실서비스 목적이라면 마이페이지에서 운영계정 전환 또는 트래픽 한도 증가를 신청하세요.

Korea Weather MCP 서버가 제공하는 기능

한국 기상청 날씨 MCP 서버는 단기예보 조회서비스와 초단기실황 두 가지를 통합해 제공합니다.

기능설명갱신 주기
단기예보최대 72시간(3일) 앞 예보3시간마다
초단기실황현재 기준 최신 관측값1시간마다
지점 자동 변환지역명 → 기상청 격자(nx, ny) 좌표 자동 변환—

두 서비스는 항목 코드가 다릅니다. 예를 들어 기온은 단기예보에서 TMP, 초단기실황에서 T1H를 사용합니다. MCP 서버는 질문에 맞는 서비스를 자동으로 선택하므로, 사용자가 좌표나 코드를 직접 다룰 필요는 없습니다. 지역명(예: “서울”, “제주시”)만 입력하면 내부에서 격자 좌표로 변환해 호출합니다.

자주 묻는 질문

단기예보와 초단기실황의 차이는?

단기예보는 최대 3일(72시간) 앞을 3시간 간격으로, 초단기실황은 현재 기준 최신 관측값을 제공합니다. Korea Weather MCP 서버는 두 종류를 모두 지원하므로 질문에 맞는 데이터를 자동으로 선택해 반환합니다.

Claude 외에 다른 AI 클라이언트에도 연결할 수 있나요?

MCP 프로토콜을 지원하는 클라이언트라면 연결 가능합니다. Smithery CLI의 --client 옵션은 claude, cursor, windsurf 등을 지원합니다. 클라이언트마다 설정 파일 위치만 다를 뿐 구조는 동일합니다.

Windows에서도 같은 방법으로 설치되나요?

네. Node.js와 npx가 있으면 동일한 npx 명령을 PowerShell이나 명령 프롬프트에서 실행할 수 있습니다. 설정 파일 경로는 %APPDATA%\Claude\claude_desktop_config.json입니다.

API 키는 어디서 발급받나요?

공공데이터포털(data.go.kr)에 회원가입 후 ‘기상청_단기예보 조회서비스’ 페이지에서 활용 신청을 하면, 마이페이지에서 일반 인증키(디코딩 키)를 확인할 수 있습니다.

다음 단계

날씨를 시작으로 공공 API를 AI에 연결하면 더 실용적인 에이전트를 손쉽게 구성할 수 있습니다. 다른 가이드 보기에서 더 많은 활용법을 찾아보세요.

이 글과 관련된 MCP 서버