mcp-weather-server

A Model Context Protocol server that gives Claude (or any MCP client) live weather tools, backed by Open-Meteo — which is free and needs no API key.

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools and data sources through a common interface, instead of every app inventing its own plugin system. A client such as Claude Desktop launches an MCP server as a subprocess and talks to it over JSON-RPC, discovering and invoking whatever tools the server exposes.

Overview

I built this server to expose three weather tools:

Tool	What it does
geocode_city(name)	Resolves a city name to coordinates, country, and timezone; lists alternative matches for ambiguous names like "Springfield"
current_weather(city)	Live conditions: temperature, feels-like, humidity, wind, and a readable sky description with the matching emoji
forecast(city, days=3)	Daily forecast for 1–16 days: min/max temperature, precipitation total and probability, peak wind

Everything returns readable structured text, so the model can relay answers directly. Errors come back as plain-language messages ("No place called 'Atlantis' was found…") rather than tracebacks.

Architecture

   Claude Desktop / any MCP client
              │
              │  JSON-RPC over stdio
              ▼
┌──────────────────────────────────────┐
│ weather_mcp.server        (FastMCP)  │   thin tool layer:
│  geocode_city · current_weather ·    │   docstrings, schemas,
│  forecast                            │   text formatting
└───────────────┬──────────────────────┘
                │ typed dataclasses
                ▼
┌──────────────────────────────────────┐
│ weather_mcp.openmeteo   (pure stdlib)│   all domain logic:
│  URL building · timeouts · JSON      │   uses weather_mcp.codes
│  parsing · friendly error mapping    │   for WMO code → text/emoji
└───────┬──────────────────────┬───────┘
        │ HTTPS                │ HTTPS
        ▼                      ▼
 geocoding-api.open-meteo.com  api.open-meteo.com
 (city search)                 (current + daily forecast)

Design decisions

• Standard-library HTTP instead of requests/httpx. The only runtime dependency is the mcp SDK itself. It also gives the tests a single seam to mock (urlopen), so the whole client is unit-testable offline.
• All logic lives in openmeteo.py; server.py stays thin. The client module never imports mcp, so the test suite runs on a bare Python install with nothing pip-installed.
• Frozen, typed dataclasses at the API boundary. Tools work with Location, CurrentWeather, and DailyForecast values instead of raw dicts, so a malformed API response fails loudly at parse time, not somewhere downstream.
• Errors are phrased for end users. Network failures, timeouts, HTTP errors, and unknown cities all map to WeatherError subclasses whose messages the tools return verbatim — an LLM can relay "check the spelling" far more usefully than a stack trace.
• Open-Meteo as the data source. No API key, no signup, generous free limits — anyone can clone this repo and have working weather tools in under a minute.
• Timeouts on every request (10 s default, overridable per call), so a hung network call can never wedge the server.

Quickstart

Requires Python 3.11+.

git clone https://github.com/srathish/mcp-weather-server.git
cd mcp-weather-server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m weather_mcp        # starts the server on stdio

Claude Desktop

Add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), using the absolute path to your clone:

{
  "mcpServers": {
    "weather": {
      "command": "/absolute/path/to/mcp-weather-server/.venv/bin/python",
      "args": ["-m", "weather_mcp"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-weather-server"
      }
    }
  }
}

Restart Claude Desktop and ask something like "What's the weather in Berlin right now?" — Claude will call current_weather for you.

MCP Inspector

For interactive debugging, the official inspector works out of the box:

pip install "mcp[cli]"
mcp dev weather_mcp/server.py

This opens a web UI where you can invoke each tool by hand and inspect the requests and responses.

How I know it works

The test suite covers the parts that can actually break: geocoding parsing (including the no-results case), current-weather and forecast parsing, WMO code mapping (including the unknown-code fallback), the mapping of HTTP/network/timeout failures onto friendly messages, and URL construction (parameters and non-ASCII city names encoded correctly).

All HTTP is mocked at the urlopen seam, so the tests use only the standard library — no pip installs, no network:

python3 -m unittest discover -s tests -v

28 tests, all passing on Python 3.11+.

Limitations

• Geocoding trusts the top match. current_weather("Springfield") picks Open-Meteo's best-ranked Springfield. Use geocode_city first when a name is ambiguous.
• Metric units only. Temperatures are °C and wind speeds km/h; I have not added unit conversion.
• No caching or rate limiting. Every tool call is a fresh API request. Open-Meteo's free tier is generous, but a busy deployment would want a small TTL cache.
• Forecast only, no history. The server exposes current conditions and up to 16 days ahead; Open-Meteo's historical archive endpoints are not wired up.
• Output is text, not JSON. The tools return human-readable text for the model to relay. If a downstream program needed to parse results, structured output would be the better contract.

License

MIT — see LICENSE.