Model Context Protocol

내 AI 비서에게
한국 날씨와 시간을 Korean weather & time
for LLM agents

AI가 한국 날씨와 시간을 지어내지 않고 직접 찾아보게 해줍니다. Hermes·GoClaw·Claude Code 같은 곳에 등록해서 쓰시면 됩니다. Wire it into Hermes, GoClaw, OpenClaw or Claude Code so the model looks up Korean time and KMA weather instead of inventing them. Locations by name, coded values decoded server-side.

PyPI GitHub 서비스 키 발급Get an API key

uvx oc-korea-weather-time-mcp

답답해서 직접 만들었습니다Built it out of frustration

"지금 서울 몇 도야" 한마디에 엉뚱한 답이 돌아오는 게 답답해서요. Tired of asking “how warm is it in Seoul right now” and getting a made-up number.

MCP가 뭔가요What is MCP?

AI가 외부 도구를 갖다 쓸 수 있게 해주는 공개 규격입니다. 예전에는 앱마다 연동을 따로 만들어야 했는데, 이제는 MCP 서버 하나만 만들어 두면 이 규격을 지원하는 어느 AI에서든 그대로 씁니다. Model Context Protocol — an open standard that lets an LLM call external tools. It replaces one-off, per-app integrations with a single protocol: write one MCP server and every agent that speaks MCP can use it as-is.

이 프로젝트가 그 서버입니다. 한 번 등록해 두시면, AI가 필요할 때 알아서 get_current_weather("인천") 같은 걸 호출해서 답을 만듭니다. This project is such a server. Register it once and the model decides when to call something like get_current_weather("인천"), then answers from what comes back.

AI는 오늘이 며칠인지, 지금 몇 시인지, 밖이 더운지 모릅니다. 학습한 시점에 멈춰 있고 시계도 없으니까요. 그래서 한국 시간이나 날씨를 물어보면 그럴듯한 숫자를 지어냅니다. 이 서버가 그 두 가지를 진짜 출처에서 가져다 줍니다. 시간은 IANA 시간대 데이터, 날씨는 기상청입니다. A model does not know today’s date, the current hour, or whether it is hot outside. It is frozen at training time and has no clock, so asking it about Korean time or Korean weather gets you a plausible-looking guess. This server fetches both from the actual sources — IANA timezone data and the Korea Meteorological Administration.

MCP를 지원하면 어디든 붙습니다. 만들면서 실제로 연결해 본 곳은 이렇습니다. It plugs into anything that speaks MCP. These are the hosts it was actually wired into while being built.

Hermes Agentstdio
GoClawstdio
OpenClawstdio
Claude Codestdio

텔레그램 봇으로 돌리는 개인 비서에 특히 잘 맞습니다. "내일 아침 인천 비 와?" 한마디에 강수확률까지 붙여서 답하게 하려고 만들었습니다. It fits personal assistants that live in a Telegram bot especially well — built so that “will it rain in Incheon tomorrow morning?” comes back with the actual precipitation probability attached.

툴 6개Six tools

툴 설명이 매번 AI에게 통째로 전달되기 때문에, 개수를 일부러 늘리지 않았습니다. Tool definitions ride along in every request, so the set is kept small.

날씨 · 기상청 단기예보Weather · KMA forecast

get_current_weather(location) 초단기실황nowcast 지금 기온·습도·비/눈·바람Observed temperature, humidity, precipitation type, wind

get_hourly_forecast(location, hours) 초단기예보6-hour 앞으로 6시간, 한 시간 단위 예보Hour-by-hour forecast for the next six hours

get_daily_forecast(location, slots) 단기예보3-day 앞으로 3일치. 강수확률과 최저·최고기온은 여기에만 있습니다Up to three days. Precipitation probability and daily min/max live only here

시간 · 표준 라이브러리만Time · stdlib only

get_current_time(timezone) zoneinfo 현재 시각. 요일과 UTC 오프셋도 같이 줍니다Current time, with UTC offset, weekday and epoch seconds

convert_time(time, from_tz, to_tz) zoneinfo 시간대끼리 변환합니다. 서머타임도 알아서 반영됩니다Convert between zones; DST comes from the IANA database

find_timezone(query) zoneinfo 시간대 이름을 찾아줍니다Search IANA timezone names

지역 지정Locations

위경도를 몰라도 됩니다. 안 적으면 기본 지역으로 조회합니다. No coordinates to memorise. Omit it and the default location is used.

# 이름, 다른 표기, 일부만 적기, 좌표 모두 됩니다# Names, aliases, partial matches and raw coordinates all work
get_current_weather("서울")
get_current_weather("부산광역시")
get_current_weather("성남시 분당구")
get_current_weather("37.5665,126.978")
get_current_weather()            → KMA_DEFAULT_LOCATION

없는 지역을 넣으면 쓸 수 있는 지역 목록을 같이 돌려줍니다. 목록 전용 툴을 따로 두면 매번 프롬프트만 무거워져서 이렇게 했습니다. An unknown location comes back as an error carrying the supported list. A dedicated listing tool would cost prompt space on every single request.

설치하기Setup

uvx가 실행할 때 알아서 받아옵니다. 따로 설치하실 게 없습니다. uvx fetches and runs it on demand — there is no install step.

Claude Code
claude mcp add oc-korea-weather-time \
  -e KMA_SERVICE_KEY=… -e KMA_DEFAULT_LOCATION=서울 \
  -- uvx oc-korea-weather-time-mcp

Hermes Agent
hermes mcp add oc-korea-weather-time \
  --command uvx --args oc-korea-weather-time-mcp \
  --env KMA_SERVICE_KEY=… KMA_DEFAULT_LOCATION=서울

mcp.json — GoClaw · OpenClaw 등— GoClaw, OpenClaw and friends
{
  "command": "uvx",
  "args": ["oc-korea-weather-time-mcp"],
  "env": { "KMA_SERVICE_KEY": "…" }
}

버전을 고정하시려면 oc-korea-weather-time-mcp@0.1.0처럼 붙이세요. 그냥 두면 새 버전이 나올 때 알아서 바뀝니다. Pin a version with oc-korea-weather-time-mcp@0.1.0. By default uvx tracks the latest release, so it will change under you when one ships.

공공데이터포털에서 기상청_단기예보 조회서비스를 신청하시고 일반 인증키(Decoding)를 쓰세요. 인코딩 키를 넣으면 인증이 안 됩니다. Request access to 기상청_단기예보 조회서비스 on data.go.kr and use the Decoding key. The encoded variant fails auth because it gets URL-encoded twice.

# 한쪽만 쓰실 때. 그만큼 가벼워집니다# Use only one half and the prompt gets lighter
OC_KOREA_MCP_TIME=0       → 날씨 3 개만→ weather only
OC_KOREA_MCP_WEATHER=0    → 시간 3 개만→ time only

설계 메모Design notes

기상청 API를 쓰다 보면 다들 한 번씩 걸리는 것들입니다. The things anyone hits when they wire up this API.

격자 변환Grid projection

기상청은 위경도를 안 받고 자체 격자 좌표를 씁니다. 변환 공식을 직접 구현했고, 서울(60,127)·부산(98,76)·제주(53,38) 공식 값과 맞는지 확인했습니다. The API takes its own grid, not lat/lon. The Lambert Conformal Conic projection is implemented here and checked against the published reference points — Seoul (60,127), Busan (98,76), Jeju (53,38).

발표 시각Base time

초단기 예보는 매시 40분에 나옵니다. 정시 직후에 그 시각으로 부르면 빈 응답이 옵니다. 그래서 40분 전이면 한 시간 전 것을 씁니다. 단기예보는 하루 여덟 번 나옵니다. Nowcasts are published at :40. Ask for the current hour right after the hour and you get an empty body, so before :40 the previous hour is used. The 3-day forecast publishes eight times a day.

코드값을 서버가 푼다Codes are decoded server-side

SKY=1을 그대로 넘기면 AI가 알아서 지어냅니다. 맑음으로 풀어서 보내되, 모르는 코드는 억지로 해석하지 않고 그대로 표시합니다. Handing SKY=1 to a model invites invention. It is decoded here — and codes not in the table are surfaced as unknown rather than guessed at.

단위는 수치에만Units only on numbers

기상청은 강수량 자리에 강수없음 같은 글자를 섞어 보냅니다. 숫자일 때만 단위를 붙입니다. 안 그러면 강수없음mm가 됩니다. The precipitation field sometimes carries text instead of a number. Units are appended only to numeric values, otherwise you get nonsense like 강수없음mm.

오류를 예외로 던지지 않는다Failures are values, not exceptions

실패해도 툴이 {"오류": …}를 돌려줍니다. AI가 다음에 뭘 할지 정할 수 있어야 하니까요. 키가 없으면 받는 방법까지 같이 알려줍니다. Tools return a structured error so the model can decide what to do next. A missing key comes back with instructions for getting one.

키는 환경변수로만Keys stay in the environment

httpx는 요청 주소를 통째로 로그에 찍는데, 거기에 서비스 키가 들어 있습니다. 그대로 두면 로그에 키가 남아서 해당 로그를 꺼뒀습니다. httpx logs full request URLs at INFO, and the service key lives in the query string. Left alone it lands in your logs in the clear, so those loggers are turned down.