openmeteo-mcp

A reference-quality demo MCP server: six narrow, well-typed weather tools over the free, keyless Open-Meteo API.

This repo exists to demonstrate what senior MCP server craft looks like — typed input schemas with range constraints, deliberate response sizing, TTL caching matched to upstream update cadence, error messages written for an LLM caller, hermetic tests, and CI. It is intentionally small enough to read in one sitting (src/ is ~690 lines).

Built on the official MCP Python SDK (v2.x, MCPServer), served over stdio.

Why Open-Meteo?

• Zero credentials. No API key, no signup, no env vars — anyone can clone this repo and have a working MCP server in under a minute. For a public demo, an auth-free upstream removes the single biggest source of setup friction and secret-handling risk.

• Real utility, four distinct services. Geocoding, forecast, air quality, and a historical archive (ERA5, back to 1940) under one provider. That variety is exactly what rewards narrow-tool decomposition instead of one god-tool with mode flags.

• Well-behaved API surface. Stable JSON, per-field units, and a machine-readable reason on errors — which this server surfaces verbatim so callers get actionable messages instead of opaque HTTP codes.

• Generous free tier (10,000 calls/day) — and this server stays far below it thanks to TTL caching.

Related MCP server: open-meteo-mcp-server

Tools

Every tool is annotated readOnlyHint = true, destructiveHint = false, idempotentHint = true, openWorldHint = true.

Design principles

• Narrow tools, not a god-tool. One tool per question a user actually asks. Clients see small schemas; the LLM can't pick a wrong "mode".

• Validation at the schema. Ranges (ge/le), string lengths, regex date patterns, and enum units are declared in the tool signature, so invalid arguments are rejected before any network call — and the JSON Schema is visible to clients in tools/list.

• Response size discipline. Columnar API arrays are zipped into compact row dicts with units attached, lists are capped (and defensively re-sliced even if upstream ignores the cap), geocoding drops junk fields like postcodes, and WMO weather codes are expanded inline to weather_description so no second lookup is needed.

• TTL cache tuned to data cadence. Current observations change every ~15 min → 10 min TTL; forecasts → 15 min; place metadata and archive data are effectively immutable → 24 h. Bounded at 256 entries with expire-first/FIFO eviction.

• Errors written for an LLM. Upstream reason text is surfaced verbatim; timeouts/network failures explain what happened and suggest a retry; validation failures name the field and the constraint.

Quickstart

git clone <this-repo> && cd mcp-demo-weather
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# hermetic test suite (56 tests, no network)
.venv/bin/python -m pytest

# real end-to-end check: spawns the server over stdio, performs the MCP
# handshake, lists tools, and makes live calls to Open-Meteo
.venv/bin/python scripts/verify_stdio.py

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "open-meteo": {
      "command": "/absolute/path/to/mcp-demo-weather/.venv/bin/python",
      "args": ["-m", "openmeteo_mcp.server"]
    }
  }
}

Cursor

~/.cursor/mcp.json (same shape):

{
  "mcpServers": {
    "open-meteo": {
      "command": "/absolute/path/to/mcp-demo-weather/.venv/bin/python",
      "args": ["-m", "openmeteo_mcp.server"]
    }
  }
}

Once published, uvx --from git+https://github.com/<you>/mcp-demo-weather openmeteo-mcp also works as the command (the console script runs the same stdio server).

Architecture

src/openmeteo_mcp/
├── server.py    # MCPServer instance + 6 tools: schema-typed inputs,
│                # response shaping/truncation, APIError → ToolError mapping
├── client.py    # async httpx wrapper: one fixed base URL per Open-Meteo
│                # service, coordinate validation, per-endpoint TTL cache
│                # wiring, error normalization
├── cache.py     # TTLCache: bounded, thread-safe, lazy expiry,
│                # expire-first-then-FIFO eviction (~90 lines, no deps)
└── wmo.py       # WMO 4677 weather-code → plain-language table

Request flow: tools/call → pydantic schema validation → OpenMeteoClient (cache hit? return) → httpx GET to a fixed allowlisted host → response validated/normalized → zipped, truncated, annotated rows → structured JSON back to the client. Logs go to stderr only (stdout carries the protocol).

tests/            # hermetic: respx mocks every upstream response
scripts/verify_stdio.py   # live smoke: real handshake + real tool calls
.github/workflows/ci.yml  # pytest on Python 3.11/3.12/3.13

Security posture

• Read-only. Every tool is a lookup; nothing writes, executes, or retains user data. Annotations declare this machine-readably.

• No credentials, no env, no config. There is nothing to leak; the server works with a completely empty environment.

• No URL injection surface. Base URLs are module constants; caller input only ever becomes typed query parameters (floats/ints/enums/date patterns). A tool call cannot redirect the server to another host.

• No tool-poisoning surface. Tool names, descriptions, and annotations are static code — never derived from upstream responses or user input.

• Bounded in and out. Input ranges at the schema; output caps (72 h / 10 days / 366-day archive spans) and defensive re-slicing keep responses context-window sized.

• Timeboxed network. 10 s httpx timeout, no redirects, single retry-free attempt with clear errors — no hanging tool calls.

• stdio discipline. Protocol on stdout, logs on stderr; no files, subprocesses, or shell anywhere in the codebase.

Verification

Both of these were run against the initial commit:

$ .venv/bin/python -m pytest -q
56 passed in 0.33s

$ .venv/bin/python scripts/verify_stdio.py
== initialize ==
serverInfo: open-meteo v0.1.0 | protocol: 2025-11-25
== tools/list ==
6 tools: geocode_location, get_air_quality, get_current_weather,
         get_daily_forecast, get_historical_weather, get_hourly_forecast
== tools/call: geocode_location {"name": "Reykjavik"} ==
{"count": 1, "results": [{"name": "Reykjavik", "country": "Iceland",
  "latitude": 64.13548, "longitude": -21.89541, "timezone": "Atlantic/Reykjavik", ...}]}
== tools/call: get_current_weather (live coordinates) ==
{"timezone": "Atlantic/Reykjavik", "current": {"temperature_2m": -0.7,
  "weather_code": 0, "weather_description": "Clear sky", "is_day": true, ...}}
== tools/call: schema violation ==
isError=True
Error executing tool get_current_weather: ... Input should be less than or equal to 90 ...
VERIFY OK: handshake, tools/list, 2 live tool calls, 1 clean error path

CI runs the same suite on every push/PR across Python 3.11–3.13.

License

MIT © 2026 Dylan Sproule. Weather data by Open-Meteo (free for non-commercial use; see their terms).