oc-korea-weather-time-mcp
기상청 날씨와 시간대 조회를 제공하는 MCP 서버.
uvx oc-korea-weather-time-mcp
왜 만들었나
- 기존
korea-weather-mcp는 개인 개발자가 2025-09 에 v0.1.0 한 번 올리고 방치했고 초단기실황만 지원한다. - 자격증명(기상청 서비스 키)을 다루는 물건은 직접 관리한다는 방침.
- 날씨와 시간은 어차피 같이 쓰인다 — "내일 아침 서울 날씨" 를 답하려면 둘 다 필요하다.
툴
날씨 (기상청 단기예보 조회서비스)
| 툴 | 출처 API | 범위 |
|---|---|---|
get_current_weather(location="") |
초단기실황 | 지금 관측값 |
get_hourly_forecast(location="", hours=6) |
초단기예보 | 앞으로 6시간 |
get_daily_forecast(location="", slots=24) |
단기예보 | 앞으로 3일 |
location 은 지역명(서울·인천·부산광역시), 부분 일치(성남시 분당구),
또는 위도,경도 문자열을 받는다. 생략하면 KMA_DEFAULT_LOCATION(기본 서울).
모르는 지역이면 오류 응답에 지원 목록을 실어 보낸다 — 목록 전용 툴을 두면
매 요청 프롬프트에 비용이 붙기 때문이다.
강수확률(POP)과 일최저/최고기온은 단기예보에만 있다.
시간
| 툴 | 하는 일 |
|---|---|
get_current_time(timezone="Asia/Seoul") |
지정 시간대의 현재 시각 |
convert_time(time, from_timezone, to_timezone) |
시간대 간 변환 |
find_timezone(query) |
IANA 시간대 이름 검색 |
시간 쪽은 파이썬 표준 zoneinfo 만 쓴다. 외부 의존이 없다.
설정
export KMA_SERVICE_KEY="발급받은-디코딩-키" # 날씨 툴에 필수
export KMA_DEFAULT_LOCATION="서울" # 선택
서비스 키는 공공데이터포털 → 기상청_단기예보 조회서비스
활용신청 → 일반 인증키(Decoding). 인코딩 키(%2B 가 섞인 것)를 넣으면
이중 인코딩으로 인증에 실패한다.
키는 환경변수로만 받는다. httpx 가 INFO 레벨에서 요청 URL 전체를 찍는데
쿼리스트링에 serviceKey 가 들어 있어 키가 로그에 평문으로 남는다.
그래서 httpx·httpcore 로거를 WARNING 으로 낮춘다.
한쪽만 쓰기
툴 정의는 매 요청마다 프롬프트에 실린다. 필요 없는 쪽은 끄면 그만큼 가벼워진다.
export OC_KOREA_MCP_TIME=0 # 날씨 툴 3개만
export OC_KOREA_MCP_WEATHER=0 # 시간 툴 3개만
등록
# Claude Code
claude mcp add oc-korea-weather-time \
-e KMA_SERVICE_KEY=발급받은-키 \
-- uvx oc-korea-weather-time-mcp
# Hermes
hermes mcp add oc-korea-weather-time \
--command uvx --args oc-korea-weather-time-mcp \
--env KMA_SERVICE_KEY=발급받은-키
설계 메모
- 격자 변환 — 기상청 API 는 위경도를 안 받고 자체 격자(nx, ny)를 쓴다. Lambert Conformal Conic 투영, 파라미터는 기상청 고시값. 서울(60,127)·부산(98,76)·제주(53,38) 표준 검증값과 일치를 확인했다.
- 코드 해석 — API 는
SKY=1같은 숫자만 준다. 그대로 넘기면 LLM 이 해석을 지어내므로 서버에서맑음으로 풀어 넘긴다. 매핑에 없는 코드는 임의 해석하지 않고알 수 없음(값)으로 표시한다. - 단위 — 기상청은 강수량 자리에
강수없음같은 문자열을 섞어 보낸다. 수치일 때만 단위를 붙인다. - 발표시각 — 초단기는 매시 40분 생성이라 그 전이면 한 시간 전 발표분을 쓴다. 단기예보는 하루 8회(02·05·08·11·14·17·20·23시) 발표.
- 오류를 예외로 던지지 않는다. 툴은
{"오류": "..."}를 돌려준다. LLM 이 다음 행동을 정할 수 있어야 한다.
개발
uv venv && uv pip install -e . pytest
uv run pytest tests/ -q
외부 호출 없이 격자 변환·발표시각·지역 해석·표시 변환을 검증한다. API 호출 경로는 네트워크와 키가 필요하므로 테스트에서 제외했다.
라이선스
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file oc_korea_weather_time_mcp-0.1.0.tar.gz.
File metadata
- Download URL: oc_korea_weather_time_mcp-0.1.0.tar.gz
- Upload date:
- Size: 17.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
69769cfd811aba907d9ab34f385891ae501dd8478c0b1bd30073a5e918efff72
|
|
| MD5 |
e6374a2e23935cce9fed2cc7f6a6c4d8
|
|
| BLAKE2b-256 |
3ec3fa87aaad73de5cb3e1adab9a8587cd461633d56b25c6d66ac3c5a94b9fa3
|
Provenance
The following attestation bundles were made for oc_korea_weather_time_mcp-0.1.0.tar.gz:
Publisher:
publish.yml on jshsakura/oc-korea-weather-time-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
oc_korea_weather_time_mcp-0.1.0.tar.gz -
Subject digest:
69769cfd811aba907d9ab34f385891ae501dd8478c0b1bd30073a5e918efff72 - Sigstore transparency entry: 2417294614
- Sigstore integration time:
-
Permalink:
jshsakura/oc-korea-weather-time-mcp@839451736872b1c57e5848fc3f50d4ae194a6960 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/jshsakura
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@839451736872b1c57e5848fc3f50d4ae194a6960 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file oc_korea_weather_time_mcp-0.1.0-py3-none-any.whl.
File metadata
- Download URL: oc_korea_weather_time_mcp-0.1.0-py3-none-any.whl
- Upload date:
- Size: 18.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
327622851931f406b21623ebe4fedadee9f9cc3e6fe6cfd1402a4c9fc8dbb051
|
|
| MD5 |
86a77bb655a13d9bd367594981d22d51
|
|
| BLAKE2b-256 |
bb46be1e25d9e4135248d608774241b4a5b6e70a6d5ba72be806888bc38785bb
|
Provenance
The following attestation bundles were made for oc_korea_weather_time_mcp-0.1.0-py3-none-any.whl:
Publisher:
publish.yml on jshsakura/oc-korea-weather-time-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
oc_korea_weather_time_mcp-0.1.0-py3-none-any.whl -
Subject digest:
327622851931f406b21623ebe4fedadee9f9cc3e6fe6cfd1402a4c9fc8dbb051 - Sigstore transparency entry: 2417294823
- Sigstore integration time:
-
Permalink:
jshsakura/oc-korea-weather-time-mcp@839451736872b1c57e5848fc3f50d4ae194a6960 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/jshsakura
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@839451736872b1c57e5848fc3f50d4ae194a6960 -
Trigger Event:
workflow_dispatch
-
Statement type:
