Plinth Weather MCP Server

A production-clean MCP server for the free Open-Meteo weather API (geocoding, forecast, air quality) with SRE-grade rate limiting, backoff, and structured logging.

GitHub

Documentation

Plinth Weather MCP

A small, production-clean Model Context Protocol server that gives any MCP client (Claude Desktop, Claude Code, Cursor, ...) real-time weather data — geocoding, current conditions, multi-day forecasts, and air quality — from the free, no-API-key Open-Meteo service.

It's free and MIT-licensed. The point isn't just "weather in your LLM" — it's a reference for what an MCP server should look like when you actually have to run it: rate-limited, retried, observable, and validated.

Why this one

Most example MCP servers are toys that fall over the first time an LLM calls a tool in a loop or the upstream hiccups. This one ships the boring stuff that keeps a server alive in production:

Outbound rate limiting — a token bucket caps how fast we hit the upstream, so an over-eager agent can't get you throttled.
Exponential backoff with full jitter — transient 429/5xx/network errors are retried with capped, jittered delays that honor Retry-After.
Structured JSON logging to stderr — one JSON object per line, ready for a log shipper. Never writes to stdout (that's the JSON-RPC channel — polluting it corrupts the session).
Graceful shutdown — SIGTERM/SIGINT close the HTTP client cleanly.
Input validation on every tool argument — bad coordinates or empty queries fail fast with a clear, model-recoverable error instead of a stack trace.
A real health check tool — reports version and live upstream reachability.
Optional API-key gate — off by default (the upstream is public); flip on with one env var if you expose this server to others.

Quickstart (one command)

With uv installed, no clone or install needed:

uvx plinth-weather-mcp

Or with pip:

pip install plinth-weather-mcp
plinth-weather-mcp

The server speaks MCP over stdio. It's meant to be launched by an MCP client, not run interactively — but the command above will start and block, logging a startup line to stderr, which confirms it's healthy.

Use with Claude Desktop / Claude Code

Add this to your MCP client config (for Claude Desktop: claude_desktop_config.json; for Claude Code: claude mcp add or your project's .mcp.json):

{
  "mcpServers": {
    "plinth-weather": {
      "command": "uvx",
      "args": ["plinth-weather-mcp"]
    }
  }
}

Then ask: "What's the weather in Salamanca this week, and is the air clean?"

Tools

Tool	What it does
`geocode_place(name, count=5)`	Resolve a place name to coordinates.
`current_weather(latitude, longitude)`	Current conditions for a coordinate.
`daily_forecast(latitude, longitude, forecast_days=7)`	Up to 16-day daily forecast.
`air_quality(latitude, longitude)`	PM2.5 / PM10 / ozone / European AQI.
`health_check()`	Server version + live upstream reachability.

Every data tool returns a JSON object with ok: true and the payload, or ok: false with error and message on failure.

Configuration

All optional. Defaults are tuned for the free public upstream.

Env var	Default	Purpose
`PLINTH_API_KEY`	(unset)	If set, every data tool requires a matching `api_key` arg.
`PLINTH_LOG_LEVEL`	`INFO`	`DEBUG` / `INFO` / `WARNING` / `ERROR`.
`PLINTH_RATE_LIMIT_REQUESTS`	`5`	Max upstream requests per window.
`PLINTH_RATE_LIMIT_WINDOW_SECONDS`	`1.0`	Rate-limit window length.
`PLINTH_MAX_RETRIES`	`4`	Retries on transient upstream failures.
`PLINTH_BACKOFF_BASE_SECONDS`	`0.5`	Base for exponential backoff.
`PLINTH_BACKOFF_MAX_SECONDS`	`20.0`	Backoff cap.
`PLINTH_REQUEST_TIMEOUT_SECONDS`	`15.0`	Per-request timeout.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Tests mock the network (via respx), so they pass fully offline.

Want the whole toolkit?

This repo is one polished example. If you're building MCP servers for real and want to skip the yak-shaving:

→ MCP Server Starter Kit

Both Python and TypeScript templates, more worked examples, Dockerfiles, and a deploy + directory-publishing guide (how to actually get your server listed in the MCP registries). Same SRE hygiene as this repo, batteries included.

More from the brand at plinthkit.vercel.app.