Getting Started¶

This guide will help you set up and start using kma-mcp to access Korean weather data from the KMA API Hub.

Note: All APIs in this package are based on the official KMA API Hub specifications. You'll need a KMA API Hub account and API key to use these services.

This guide focuses on the Python implementation. For TypeScript, see the TypeScript Overview.

Prerequisites¶

Python 3.13+ (for Python implementation) OR TypeScript 5.7+ (for TypeScript implementation)
Git
KMA API Hub account and API key

Installation¶

1. Install uv¶

First, install uv if you haven't already:

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone and Setup Project¶

# Clone the repository
git clone https://github.com/appleparan/kma-mcp.git
cd kma-mcp

# Install Python 3.13
uv python install 3.13
uv python pin 3.13

# Install dependencies
uv sync

# Install with dev tools (for development)
uv sync --group dev --group docs

3. Get API Key¶

Visit the official KMA API Hub to obtain your API key:

Go to https://apihub.kma.go.kr/
Create an account (requires Korean mobile phone verification)
Navigate to "마이페이지" (My Page) after logging in
Request an API key for the weather services you need
Once approved, copy your API key from the API management section

Important: The API key provides access to the official KMA weather data services. All API endpoints in this package correspond to services documented at https://apihub.kma.go.kr/api.

4. Configure API Key¶

Set your API key as an environment variable:

# Method 1: Environment variable
export KMA_API_KEY='your_key_here'

# Method 2: .env file (recommended)
echo "KMA_API_KEY=your_key_here" > .env

5. Verify Installation¶

Test the installation:

# Run tests
uv run pytest

# You should see: 198 passed

Quick Start Examples¶

Example 1: Get Current Weather¶

from kma_mcp.surface.asos_client import ASOSClient
import os

# Get API key from environment
api_key = os.getenv('KMA_API_KEY')

# Get current weather for Seoul (station 108)
with ASOSClient(api_key) as client:
    data = client.get_hourly_data(tm='202501011200', stn=108)
    print(data)

Example 2: Get Weather Period Data¶

from kma_mcp.surface.asos_client import ASOSClient
from datetime import datetime

with ASOSClient(api_key) as client:
    # Get hourly data for last 24 hours
    data = client.get_hourly_period(
        tm1='202501010000',
        tm2='202501020000',
        stn=108  # Seoul
    )
    print(f"Retrieved {len(data)} hours of data")

Example 3: Using Async Client¶

import asyncio
from kma_mcp.surface.async_asos_client import AsyncASOSClient

async def get_weather():
    async with AsyncASOSClient(api_key) as client:
        data = await client.get_hourly_data(tm='202501011200', stn=108)
        return data

# Run async function
data = asyncio.run(get_weather())

Example 4: Multiple Concurrent Requests¶

import asyncio
from kma_mcp.surface.async_asos_client import AsyncASOSClient

async def get_multiple_stations():
    async with AsyncASOSClient(api_key) as client:
        # Get weather for multiple cities concurrently
        tasks = [
            client.get_hourly_data(tm='202501011200', stn=108),  # Seoul
            client.get_hourly_data(tm='202501011200', stn=159),  # Busan
            client.get_hourly_data(tm='202501011200', stn=184),  # Jeju
        ]
        results = await asyncio.gather(*tasks)
        return results

data = asyncio.run(get_multiple_stations())
print(f"Retrieved data for {len(data)} stations")

Example 5: Using Korean Weather Utilities¶

from kma_mcp.surface.asos_client import ASOSClient
from kma_mcp.utils.weather_codes import (
    enhance_weather_data,
    format_weather_summary
)

with ASOSClient(api_key) as client:
    data = client.get_hourly_data(tm='202501011200', stn=108)

    # Add Korean language fields
    enhanced = enhance_weather_data(data)

    # Generate human-readable summary
    summary = format_weather_summary(enhanced)
    print(summary)
    # Output: "기온 15.2°C, 날씨 맑음, 풍향 서풍, 풍속 3.2m/s"

Running the MCP Server¶

Start the Server¶

uv run python scripts/start_mcp_server.py

Configure in Claude Desktop¶

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "kma-weather": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/path/to/kma-mcp/scripts/start_mcp_server.py"
      ],
      "env": {
        "KMA_API_KEY": "your_key_here"
      }
    }
  }
}

Common Station IDs¶

Station ID	Location	Korean Name
108	Seoul	서울
112	Incheon	인천
133	Daejeon	대전
143	Daegu	대구
156	Gwangju	광주
159	Busan	부산
184	Jeju	제주
0	All stations	모든 지점

For a complete list, use:

from kma_mcp.surface.station_client import StationClient

with StationClient(api_key) as client:
    stations = client.get_asos_stations()
    for station in stations:
        print(f"{station['stn_id']}: {station['stn_ko']}")

Time Format Guide¶

String Formats¶

Hourly data: YYYYMMDDHHmm (e.g., 202501011200 = 2025-01-01 12:00)
Daily data: YYYYMMDD (e.g., 20250101 = 2025-01-01)

Python datetime Objects¶

All clients accept Python datetime objects:

from datetime import datetime

# These are equivalent
data1 = client.get_hourly_data(tm='202501011200', stn=108)
data2 = client.get_hourly_data(tm=datetime(2025, 1, 1, 12, 0), stn=108)

API Categories¶

kma-mcp provides access to 11 major categories:

Surface Observations - Ground weather stations (ASOS, AWS, etc.)
Marine Observations - Ocean buoy data
Upper-Air Observations - Atmospheric vertical profiles (radiosondes)
Radar - Precipitation detection and tracking
Satellite - GK2A satellite imagery
Earthquakes - Seismic activity monitoring
Typhoon - Tropical cyclone tracking
Forecasts & Warnings - Weather predictions and alerts
Global Meteorology - GTS worldwide data
Aviation Meteorology - Airport and aircraft weather
Integrated Meteorology - Lightning and wind profiler data

See API Categories for detailed documentation of each category.

Development Workflow¶

Code Quality¶

# Format code
uv run ruff format

# Lint code
uv run ruff check --fix .

# Type checking
uv run mypy src/

# Run pre-commit hooks
uvx pre-commit run --all-files

Testing¶

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=kma_mcp

# Run specific test file
uv run pytest tests/surface/test_asos_client.py

# Run verbose
uv run pytest -v

Documentation¶

# Serve documentation locally (with auto-reload)
uv run mkdocs serve

# Build documentation
uv run mkdocs build

# Deploy to GitHub Pages
uv run mkdocs gh-deploy

Configuration¶

Environment Variables¶

KMA_API_KEY - Your KMA API Hub key (required)
KMA_TIMEOUT - Request timeout in seconds (default: 30.0)

.env File Example¶

# .env
KMA_API_KEY=your_key_here
KMA_TIMEOUT=60.0

Load automatically with:

from dotenv import load_dotenv
load_dotenv()

Error Handling¶

Common Errors¶

401 Unauthorized

# Invalid API key
# Solution: Check your API key in .env file

429 Too Many Requests

# Rate limit exceeded
# Solution: Wait or upgrade to premium tier

404 Not Found

# Invalid endpoint or parameters
# Solution: Check station ID and time format

Error Handling Example¶

import httpx
from kma_mcp.surface.asos_client import ASOSClient

try:
    with ASOSClient(api_key) as client:
        data = client.get_hourly_data(tm='202501011200', stn=108)
except httpx.HTTPStatusError as e:
    print(f"HTTP error {e.response.status_code}: {e.response.text}")
except httpx.RequestError as e:
    print(f"Request failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Performance Tips¶

Use Async for Multiple Requests¶

# BAD: Sequential (slow)
with ASOSClient(api_key) as client:
    data1 = client.get_hourly_data(tm='202501011200', stn=108)
    data2 = client.get_hourly_data(tm='202501011200', stn=159)

# GOOD: Concurrent (fast)
async with AsyncASOSClient(api_key) as client:
    data1, data2 = await asyncio.gather(
        client.get_hourly_data(tm='202501011200', stn=108),
        client.get_hourly_data(tm='202501011200', stn=159)
    )

Cache Frequently Accessed Data¶

from functools import lru_cache

@lru_cache(maxsize=100)
def get_station_list(api_key):
    with StationClient(api_key) as client:
        return client.get_asos_stations()

Respect Rate Limits¶

import time

# Add delay between requests if needed
for stn in station_ids:
    data = client.get_hourly_data(tm='202501011200', stn=stn)
    time.sleep(0.1)  # 100ms delay

Troubleshooting¶

Import Errors¶

# Error: No module named 'kma_mcp'
# Solution: Ensure dependencies are installed
uv sync

API Key Issues¶

# Error: 401 Unauthorized
# Solution: Check API key is set correctly
echo $KMA_API_KEY

Timeout Errors¶

# Increase timeout for slow connections
client = ASOSClient(api_key, timeout=60.0)

Next Steps¶

Overview - Understand the architecture and features for both Python and TypeScript
TypeScript Overview - TypeScript implementation guide
API Categories - Explore all available APIs
Python API Reference - Detailed Python API documentation
TypeScript API Reference - Detailed TypeScript API documentation
GitHub Repository - Source code and issues

Getting Help¶

Project Documentation: https://appleparan.github.io/kma-mcp/
GitHub Issues: https://github.com/appleparan/kma-mcp/issues
GitHub Discussions: https://github.com/appleparan/kma-mcp/discussions
KMA API Hub (Official): https://apihub.kma.go.kr/
KMA API Documentation (Official): https://apihub.kma.go.kr/api