The py-mcp-ko-weather project implements a Multi-platform Communication Protocol (MCP) server designed to enable AI agents to access and retrieve weather forecast information for locations within South Korea, leveraging Korea Meteorological Administration (KMA) APIs.

The core methodology revolves around providing two primary tools: get_grid_location and get_forecast, which are exposed to LLM clients via the MCP protocol.

1. $get_grid_location(city: str, gu: str, dong: str) -> dict$: This tool addresses the fundamental requirement of the KMA API, which operates on a specific grid coordinate system (nx, ny) rather than standard geographical coordinates. Given a Korean administrative region specified by city (city/province), gu (district/county), and dong (neighborhood/town), this tool queries an internal SQLite database. This database is populated by migrating grid coordinate data from an Excel file during setup (src/migrate.py). The tool's objective is to accurately map a human-readable location to the precise KMA grid coordinates, returning a dictionary containing nx and ny values required for subsequent forecast requests.

2. $get_forecast(city: str, gu: str, dong: str, nx: int, ny: int) -> str$: Once the KMA grid coordinates (nx, ny) are obtained, this tool is invoked. It makes a programmatic call to the KMA's ultra-short-term forecast API. The city, gu, and dong parameters are used for context in the final structured response. The API request uses the nx and ny coordinates to retrieve comprehensive weather data for that specific grid point. The data returned by the KMA API is then processed and formatted into a structured text string. This string includes:
   • Current conditions: Temperature, sky condition (e.g., Mostly clear), precipitation type, precipitation probability, humidity, wind direction, and wind speed.
   • Hourly forecast: Detailed predictions for subsequent hours including temperature, sky condition, and precipitation information.

The response format is specifically optimized for large language model (LLM) consumption, providing clear, parsable data.

The project is built on Python 3.12+ and uses uv for efficient dependency management. KMA API credentials (KO_WEATHER_API_KEY) are required for API access. It can be run locally via an MCP server utility (e.g., mcp run src/server.py) or deployed as a Docker container. Integration with LLM clients like Claude and Cursor IDE is achieved by configuring their respective MCP settings to point to the server, specifying the command and arguments for execution (e.g., uv run src/server.py or docker run py-mcp-ko-weather). The server also provides a weather://instructions resource for detailed usage documentation and incorporates a structured prompt template to guide LLMs in gathering necessary information for weather queries.