kma-mcp¶

Model Context Protocol (MCP) server for Korea Meteorological Administration API access

What is kma-mcp?¶

kma-mcp is a comprehensive MCP (Model Context Protocol) server implementation that provides programmatic access to the Korea Meteorological Administration (KMA) API Hub. It enables developers and researchers to easily access real-time and historical Korean weather data through simple, consistent Python and TypeScript interfaces.

All API implementations are based on the official KMA API Hub specifications and documentation. This ensures compatibility with the official KMA services and provides access to the same comprehensive meteorological data available through the KMA API Hub portal.

Key Features¶

🌦️ Comprehensive Weather Data Access¶

21 API clients covering surface observations, marine data, upper-air measurements, radar, satellite imagery, forecasts, warnings, typhoons, earthquakes, aviation weather, and global meteorological data
Dual implementations: Python and TypeScript for maximum flexibility
251+ comprehensive tests (198 Python + 53 TypeScript) ensuring reliability

⚡ Multiple Implementation Options¶

Python Implementation: * Synchronous clients for simple, straightforward operations * Asynchronous clients for high-performance concurrent requests * Context manager support for automatic resource cleanup * 42 total clients (21 sync + 21 async)

TypeScript Implementation: * Type-safe API clients with full TypeScript support * MCP server built with @modelcontextprotocol/sdk * 21 clients with comprehensive type definitions

🌏 Korean Weather Specialization¶

Korean weather code utilities (wind direction, precipitation types, sky conditions)
Automatic enhancement of weather data with Korean-language fields
Human-readable Korean weather summaries

📊 Implementation Status¶

Coverage: 85% of public KMA API Hub categories (11/13)

Implemented Categories:

✅ Surface Observations (지상관측) - 10 APIs
✅ Marine Observations (해양관측) - 1 API
✅ Upper-Air Observations (고층관측) - 1 API
✅ Radar (레이더) - 1 API
✅ Satellite (위성) - 1 API
✅ Earthquakes (지진/화산) - 1 API
✅ Typhoon (태풍) - 1 API
✅ Forecasts & Warnings (예특보) - 2 APIs
✅ Global Meteorology (세계기상) - 1 API
✅ Aviation Meteorology (항공기상) - 1 API
✅ Integrated Meteorology (융합기상) - 1 API

Not Implemented (no public endpoints):

❌ Numerical Models (수치모델)
❌ Industry-Specific APIs (산업특화)

Quick Start¶

Installation¶

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Install dependencies
uv sync

Get API Key¶

Visit the KMA API Hub - the official source for all Korean meteorological data
Create an account and navigate to "마이페이지" (My Page)
Generate an API key from the API management section
Set your API key:

export KMA_API_KEY='your_key_here'
# Or create a .env file with:
# KMA_API_KEY=your_key_here

Note: The API key from KMA API Hub provides access to all weather data services. All APIs in this package correspond directly to the services available on the KMA API Hub portal.

Basic Usage¶

from kma_mcp.surface.asos_client import ASOSClient

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

Run MCP Server¶

uv run python scripts/start_mcp_server.py

Project Structure¶

kma-mcp/
├── python/                      # Python implementation
│   ├── src/kma_mcp/
│   │   ├── surface/            # Surface observation clients (10 APIs)
│   │   ├── marine/             # Marine observation clients (1 API)
│   │   ├── upper_air/          # Upper-air observation clients (1 API)
│   │   ├── radar/              # Radar clients (1 API)
│   │   ├── satellite/          # Satellite clients (1 API)
│   │   ├── earthquake/         # Earthquake clients (1 API)
│   │   ├── typhoon/            # Typhoon clients (1 API)
│   │   ├── forecast/           # Forecast clients (2 APIs)
│   │   ├── global_met/         # Global meteorology clients (1 API)
│   │   ├── aviation/           # Aviation meteorology clients (1 API)
│   │   ├── integrated/         # Integrated meteorology clients (1 API)
│   │   ├── utils/              # Utility modules
│   │   └── mcp_server.py       # Main MCP server
│   └── tests/                  # Python test suite (198 tests)
├── typescript/                  # TypeScript implementation
│   ├── src/
│   │   ├── clients/            # TypeScript API clients (21 clients)
│   │   │   ├── base.ts         # Base client
│   │   │   ├── asos.ts         # ASOS client
│   │   │   ├── aws.ts          # AWS client
│   │   │   └── ...             # Other clients
│   │   └── index.ts            # MCP server entry point
│   └── tests/                  # TypeScript test suite (53 tests)
├── docs/                        # Documentation (MkDocs)
│   ├── reference/              # Python API reference (auto-generated)
│   └── reference-ts/           # TypeScript API reference (auto-generated)
├── scripts/                     # Helper scripts
├── API_STATUS.md                # Detailed API implementation status
├── llms.txt                     # LLM-friendly project documentation
└── README.md                    # Main documentation

Use Cases¶

Weather Research: Access historical and real-time Korean weather data
Climate Analysis: Long-term climate statistics and trends
Disaster Monitoring: Real-time tracking of typhoons, earthquakes, severe weather
Aviation Safety: Airport weather observations and aircraft meteorological data
Marine Operations: Ocean buoy data for maritime safety
Air Quality: PM10 yellow dust monitoring
Public Health: UV index tracking
Agricultural Planning: Seasonal observations and phenological data

Resources¶

Official KMA Resources¶

KMA API Hub: https://apihub.kma.go.kr/ - Official API portal and documentation
KMA API Documentation: https://apihub.kma.go.kr/api - Complete API specifications
Note: All APIs in this package are implemented according to official KMA API Hub specifications

This Project¶

Documentation: https://appleparan.github.io/kma-mcp/
GitHub: https://github.com/appleparan/kma-mcp

MCP Framework¶

Model Context Protocol: https://modelcontextprotocol.io/
FastMCP (Python): https://github.com/jlowin/fastmcp
TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

License¶

MIT License - See LICENSE file for details.

Contributing¶

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Built with: - Python: Python 3.13+, FastMCP, httpx, uv - TypeScript: TypeScript 5.7+, Bun, @modelcontextprotocol/sdk, axios