weather-mcp-pro

An MCP (Model Context Protocol) server that exposes real-time weather, forecast, and air-quality data as tools for LLM agents like Claude. Built on the OpenWeather API.

What is MCP?

MCP is Anthropic's open protocol for connecting LLMs to external tools and data sources through a standard client-server interface. This server exposes 4 tools that Claude (or any MCP client) can call during a conversation.

Tools

Tool	Description
get_current_weather	Current conditions for a location
get_weather_forecast	1-5 day forecast
get_air_quality	AQI + pollutant breakdown
compare_weather	Side-by-side comparison across up to 5 cities

Architecture

server.py          MCP tool definitions — thin, delegates everything
weather_client.py  Async API client — geocoding, caching, retries
models.py          Pydantic schemas for validated, typed responses
exceptions.py      Typed exceptions instead of ad-hoc error dicts
config.py          Environment/settings management

The design goal: weather_client.py is fully unit-testable without an MCP server or a live API key (see tests/), because the tool layer never touches HTTP directly.

Notably, all API calls use httpx.AsyncClient rather than the synchronous requests library — a common mistake in async def functions is using a blocking HTTP client, which stalls the event loop for every other concurrent request the server is handling.

Setup

Uses uv for dependency management.

git clone https://github.com/AsifMarwat/weather-mcp-pro.git
cd weather-mcp-pro
uv venv
uv pip install -r requirements.txt
cp .env.example .env  # add your OpenWeather API key

Get a free API key at openweathermap.org/api.

Run

uv run server.py

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather-mcp-pro": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/weather-mcp-pro", "server.py"]
    }
  }
}

Example

"What's the weather like in Peshawar right now, and how does it compare to Lahore?"

Claude calls compare_weather(["Peshawar", "Lahore"]) and returns a natural-language summary built from the structured response.

Tests

uv run pytest tests/ -v

License

MIT