Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@weather-mcp what's the weather in Tokyo for the next 3 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Weather as MCP tools, over Open-Meteo — free, no API key, global. Each forecast returns structured data for the LLM and a weather card for the user: a rendered image (as a short-lived link, not base64), or a monospace text card where no image link can be served, such as over stdio in Claude Code.
Tool | What it does |
get_forecast | Current conditions + an N-day daily forecast for a place (by name or lat/lon). Returns the data as text + a |
geocode | Resolve a place name to candidate coordinates (name, region, country, lat/lon, timezone). |
card="auto" gives an image link when the server can serve one (streamable-http with WEATHER_PUBLIC_URL
set) and the text card otherwise. A caller whose client doesn't display images from links can ask for
card="text" on any transport. The result's card field echoes the form actually returned.
Every result carries a status: ok / refused (caller-fixable input, with advice) / error (a fault).
Branch on status, not prose.
Related MCP server: mcp-weather-server
OpenWebUI's stock weather tool returned only an image — the model got nothing to reason over. This returns the data as text (the model answers from it, even a non-vision local model) and the card as a link the client renders. The image never enters the model's context as bytes (it's an out-of-band capability link, the forge-mcp pattern).
uv sync # (--system-certs behind a TLS-inspecting proxy)
# stdio (local MCP client):
uv run weather-mcp serve
# streamable-http (behind mcpo / on the LAN):
WEATHER_MCP_TOKEN=... WEATHER_PUBLIC_URL=http://your-host:8000 \
uv run weather-mcp serve --transport http --host 0.0.0.0 --port 8000
uv run pytest # no network: Open-Meteo is fakedWEATHER_PUBLIC_URL must be browser-reachable (the client loads the card) — a LAN name/IP, not an
internal container address. Without it, the card is text instead of an image link.
{
"mcpServers": {
"weather": { "command": "uv", "args": ["--directory", "/path/to/weather-mcp", "run", "weather-mcp", "serve"] }
}
}Over stdio there is no HTTP server to serve /img/<token>, so the card comes back as monospace text in a
```text fence (WEATHER_PUBLIC_URL is ignored). It renders cleanly in Claude Code's terminal and
in Claude Desktop.
Var | Default | Notes |
| — | Bearer required on streamable-http when set. |
| — | Browser-reachable base URL; enables the image card link (HTTP only). |
|
| Where card PNGs are written (served at |
|
| Card link lifetime (seconds). |
| Quito (city-level) | Fallback when a call gives neither place nor coords. Not home coordinates. |
|
| Geocoding language. |
|
| Seconds. |
docker build -t weather-mcp .
docker run --rm -p 8000:8000 -e WEATHER_MCP_TOKEN=... -e WEATHER_PUBLIC_URL=http://your-host:8000 weather-mcpThe server is stateless: no database, no volume. Card PNGs are written to WEATHER_OUT_DIR inside the
container and expire after WEATHER_IMG_TTL, so losing them on restart is fine. It needs outbound HTTPS to
the Open-Meteo API (free for non-commercial use, no key).
Auth is deliberately simple: stdio, or streamable-HTTP with a single bearer token (WEATHER_MCP_TOKEN) on a
private network, for example behind mcpo. /healthz stays open, and so
does /img/*: the client's browser loads the card without the bearer, so each card URL is an unguessable,
short-lived capability link instead. There is no OAuth, no users and no audit log, by design. To publish
it more widely, put a management layer in front of it: an MCP gateway or auth proxy that handles OAuth, users
and audit for all your servers at once.
weather-mcp is developed openly with the help of Claude (Anthropic). Commits Claude helped write carry a
Co-Authored-By: Claude trailer. The code and design are open source so the work can be inspected, reused,
and given back.
MPL-2.0 © Daniel Núñez.
Resolve a place name to candidate coordinates (name, admin region, country, lat/lon, timezone). Use it to disambiguate before get_forecast, or when a user names an ambiguous place.
Args:
query: the place name to search for.
count: max candidates to return (default 5).
language: result language (default from config).
Inputs: query (required), count, language.
Current conditions + an N-day daily forecast for a place. Returns the structured DATA in the
text block (for you to answer from) and a weather card as card_markdown: include that markdown
in your reply, unchanged, so the user sees the card.
Args:
location: a place name ("Quito", "Berlin, DE"); geocoded via Open-Meteo. Ignored if
latitude+longitude are given. With neither, the server's default location is used.
latitude/longitude: exact coordinates (both required together) — overrides `location`.
days: number of daily-forecast days, 1..16 (default 3).
units: "metric" (°C, km/h, mm — default) or "imperial" (°F, mph, in).
language: language for geocoding the place name (default from config, e.g. "en"/"es").
card: "auto" (default: an image link when this server can serve one, else a text card),
"image" (image link; falls back to text when no link can be served), "text" (a monospace
card in a ```text fence, for terminals or clients that don't show images) or "none".
Inputs: card, days, units, language, +3 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
get_forecast and geocode have clearly distinct purposes: one fetches weather data, the other resolves place names to coordinates. The get_forecast description even explains when to use geocode first to disambiguate, so there is no realistic misselection risk.
get_forecast follows a verb_noun pattern, while geocode is a bare verb with no noun. Both are snake_case and readable, so the deviation is minor rather than confusing.
Two tools is thin for a weather server; a full forecast surface typically warrants separate helpers (current conditions, hourly, alerts, history). The set is coherent but minimal, and geocode exists mainly as a support tool for get_forecast.
The forecast tool covers current conditions plus a configurable multi-day daily forecast with units, language, and card rendering, which is the core weather workflow. Gaps remain for hourly forecasts, historical/archive data, and severe-weather alerts, but agents can work around these.
Global weather via Open-Meteo: forecast, historical, marine, air quality, geocoding, elevation.
Current weather and forecast lookup as an agent tool.
Current weather and forecasts for any coordinates, backed b… — paid per call (x402/credits), 1 tools
Get current weather for any city and create images from your prompts. Streamline planning, reports…