Weather MCP Server

Give your AI assistant real weather data — 17 tools, zero API keys, zero signup, zero cost.

Weather MCP is a Model Context Protocol server that connects AI assistants (Claude, Cursor, Cline, Zed, and any other MCP client) to live weather data: forecasts, current conditions, alerts, air quality, marine conditions, lightning, radar, rivers, wildfires, and 85+ years of historical weather. It's built entirely on free public data sources — NOAA, Open-Meteo, MET Norway, USGS, NIFC, NASA FIRMS, RainViewer, and Blitzortung.org — so there is nothing to sign up for and no key to paste in. (A few optional keys unlock extras — see Optional API keys — but no tool ever requires one.)

claude mcp add weather -- npx -y @dangahagan/weather-mcp@latest

That's the whole install for Claude Code. For any other MCP client, add this to its MCP config:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@dangahagan/weather-mcp@latest"]
    }
  }
}

Then just ask:

"What's the weather in Tokyo this weekend?" "Is there any lightning near the lake right now?" "How does today compare to normal for this time of year?" "Are there wildfires within 50 miles of my cabin?" "Will there be a full moon this weekend?" "Is this a record high for today?" "How bad is the pollen in Berlin today?" "What was the weather in Paris on June 6, 1944?"

👉 [See it in action](./examples/) — real prompts like these with the answers they produced, and the raw server output behind them.

📦 Listed in the Official MCP Registry as io.github.dgahagan/weather-mcp.

✅ The official package is [`@dangahagan/weather-mcp`](https://www.npmjs.com/package/@dangahagan/weather-mcp), published from this repository via npm trusted publishing. Every release carries a signed provenance attestation tying the tarball to the exact commit and workflow that built it — verify any version without installing it:

npm view @dangahagan/weather-mcp@latest dist.attestations

Republished copies of this server exist under other npm scopes. They are MIT-licensed forks, which the license permits, but they are not maintained here and are usually many versions behind. This issue tracker covers @dangahagan/weather-mcp only — for anything installed from another scope, please report it to that package's publisher.

Why this server?

There are excellent commercial weather MCPs backed by paid APIs and full-time teams. If you need SLA-backed data, minute-level nowcasting, or premium global station coverage, they're worth a look — this project won't pretend otherwise.

Choose this one if you want:

• Genuinely free — every data source is a free public API. No trial that expires, no credit card, no rate-limited "free tier" bait.
• No API keys — install to first forecast in under a minute. Nothing to configure, nothing to leak into a repo. (Four optional keys add extras if you want them; the default configuration needs none.)
• Fully open source — MIT licensed, readable TypeScript, 4,838 tests. Audit it, fork it, fix it.
• Privacy-respecting — your queries go directly from your machine to public weather APIs. No middleman server, and no telemetry unless you opt in.
• Breadth — 17 tools covering weather, safety hazards (lightning, floods, wildfires), marine conditions, air quality, and historical data back to 1940. Most weather MCPs stop at forecasts.

The tradeoff is honest: US data (NOAA) is richer than international data (Open-Meteo), some tools are US-only, and free APIs come with fair-use rate limits. See Coverage & Limitations.

Tools

All 17 tools, documented in detail in [docs/TOOLS.md](./docs/TOOLS.md):

Default preset: with no configuration, the server exposes the basic preset — get_weather_summary (one call covers most "what's the weather?" questions), plus forecast, current_conditions, alerts, search_location, and check_service_status. Enable everything with one environment variable — see Tool Selection.

Consistent location input: every location-based tool accepts the same three forms — latitude+longitude, a saved location_name (e.g. "home"), or a free-text city_name (e.g. "Bend, Oregon", geocoded automatically). When a name is used, the response echoes the resolved place and coordinates.

Output verbosity: high-volume tools (get_forecast, get_alerts, get_weather_imagery, get_river_conditions, get_wildfire_info, get_lightning_activity) accept detail: "summary" | "standard" | "full" (default standard) to trade completeness for token cost — e.g. full returns the complete alert text, uncapped hourly forecast, every radar animation frame, and up to 25 nearby gauges/fires/strikes instead of the default 5-10.

Feature highlights

• Smart source selection — US queries use NOAA (detailed, includes forecaster narratives); everywhere else uses Open-Meteo. You never have to pick — and on a US hourly forecast the answer tells you which product you got and when NOAA last published it, so reaching for source="openmeteo" is a choice you can make rather than one made silently for you. If Open-Meteo is having an outage, a forecast outside the US is answered by MET Norway rather than failing, and says so.
• International weather alerts — get_alerts routes by country: NOAA in the US, Environment and Climate Change Canada alerts in Canada, the official national warnings of 38 European countries via EUMETNET MeteoAlarm, the national CAP feeds of India (NDMA SACHET), the Philippines (PAGASA) and Indonesia (BMKG), and the Japan Meteorological Agency's own disaster-prevention feed in Japan — shown unmodified, with the issuing service credited. Where a feed publishes geometry inline, warnings are matched to your exact point by the alert's own polygon rather than to the whole country (the Philippines and Indonesia today; Europe remains country-level). Japanese warnings are matched to your point by JMA warning area, with the Japanese name shown as published and an English gloss beside it. Border cities like Toronto get the right country's alerts, not the nearest bounding box's.
• Real observations worldwide — ask for what a station is actually reporting and get_current_conditions will read the nearest airport's METAR (source="metar"): a genuine instrument reading anywhere on earth, with the station, its distance, and the observation age always stated. Outside the US this is the difference between a measurement and a model estimate.
• Model agreement — ask "how confident is this forecast?" and compare_models=true compares five global models (GFS, ECMWF, ICON, GEM, UKMO) in one request, summarizing where they agree and where they split rather than dumping five forecasts. Spread across models is a proxy for uncertainty, not a guarantee — a tight spread can still be wrong, and the output says so.
• Ensemble spread — the sibling question: "how confident is the model itself?" ensemble_spread=true summarizes ECMWF ENS's 50 perturbed members — per-day High/Moderate/Low confidence, interquartile temperature bands, and how many members produce rain — instead of one deterministic forecast. Member fractions are raw model output, not calibrated probabilities: a confident ensemble can still be wrong, and the output says so. Mutually exclusive with compare_models; the two answer different questions.
• Saved locations — save "home", "work", or "cabin" once, then ask "what's the weather at home?" Locations persist in ~/.weather-mcp/locations.json and can be tagged with activities ("boating", "skiing") so the AI highlights what matters to you.
• Climate context — optional 30-year climate normals show how today compares: "10°F warmer than normal for this date." For US locations the normals also carry the record high/low for the date and the year it was set: "is this a record high?"
• Astronomy almanac — opt-in moon phase, illumination, moonrise/moonset, civil/nautical/astronomical twilight, and next full/new moon dates on daily forecasts (include_astronomy). Computed locally — accurate to the arcminute, works at the poles, costs zero API calls: "when does it get fully dark?"
• Safety-aware output — lightning, wildfire, flood, and marine tools include graded safety assessments and plain-language recommendations, not just raw numbers.
• Winter weather — snow depth, snowfall accumulation, and ice accumulation forecasts with sensible trace-amount filtering.
• Timezone-aware — every timestamp is rendered in the location's local time with DST handled correctly.
• Imperial or metric — pick your units server-wide (WEATHER_UNITS) or per request (units: "metric"), with fine-grained overrides (wind in knots, pressure in hPa, 24-hour clock). Defaults to imperial. See Units & Localization.
• Built-in caching — an LRU cache with per-data-type TTLs (5 minutes for alerts, 2 hours for forecasts, forever for finalized historical data) makes repeat queries return in <10ms and cuts upstream API calls by 50–80%.
• Actionable errors — failures explain what happened and link to the upstream status page instead of dumping a stack trace.
• Remote hosting — besides the local stdio server, the package ships weather-mcp-http, which serves the same tools over Streamable HTTP so a claude.ai connector or a client on another machine can reach your own instance. It requires an OAuth authorization server you run (Keycloak, Authentik and similar) and checks every request's token, including its audience. For self-hosters; there is no public instance. See docs/REMOTE_HOSTING.md.

Data sources

All free, all public, no authentication required:

Open-Meteo allows 10,000 requests/day for non-commercial use; caching keeps typical AI usage far below that. Please respect the upstream providers' fair-use terms.

Composited radar maps (get_weather_imagery with composite: true) carry the acknowledgment NASA requests for GIBS imagery, alongside the RainViewer radar credit:

Imagery provided by services from NASA's Global Imagery Browse Services (GIBS), part of NASA's Earth Science Data and Information System (ESDIS).

Installation

Recommended — npx (always latest, nothing to manage):

# Claude Code
claude mcp add weather -- npx -y @dangahagan/weather-mcp@latest

Or in any MCP client's configuration:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@dangahagan/weather-mcp@latest"]
    }
  }
}

Global install:

npm install -g @dangahagan/weather-mcp

From source:

git clone https://github.com/weather-mcp/weather-mcp.git
cd weather-mcp
npm install
npm run build

Then point your MCP client at node /absolute/path/to/weather-mcp/dist/index.js.

Requires Node.js 20+. No API keys, tokens, or accounts needed — see Optional API keys for the four that add optional extras, and Optional dependency if you want a smaller install.

Works with

Claude Desktop, Claude Code, Cline, Cursor, Zed, VS Code (GitHub Copilot), LM Studio, Postman — any client that speaks MCP. Per-client setup instructions: [docs/CLIENT_SETUP.md](./docs/CLIENT_SETUP.md).

Upgrading

• npx users: nothing to do — @latest always fetches the newest version.
• Global install: npm install -g @dangahagan/weather-mcp@latest
• From source: git pull && npm install && npm run build

Restart your MCP client after upgrading. See CHANGELOG.md for release notes.

Running more than one MCP client on this machine? Restart every one of them. All clients share a single ~/.weather-mcp/locations.json, and a client still running a version before 1.31.2 writes that file from a stale in-memory copy — it will delete saved locations that an upgraded client has since written. The hazard is the un-upgraded instance, so the protection holds only once every client on the machine has been restarted onto the new version.

Configuration

Most users need zero configuration. Everything below is optional.

Settings can go in a .env file (see .env.example) or directly in your MCP client config:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@dangahagan/weather-mcp@latest"],
      "env": {
        "ENABLED_TOOLS": "all",
        "CACHE_MAX_SIZE": "2000",
        "LOG_LEVEL": "1"
      }
    }
  }
}

Tool Selection

Control which tools are exposed to reduce context overhead:

Context cost. Every MCP client puts the tools/list result into model context on every turn, so the preset you choose is a standing cost on every request. Measured on the built server: basic 13,249 bytes (~3.3k tokens), standard 21,223 (~5.3k), full/all 31,092 (~7.8k). It scales with the number of tools, not the number of data sources — adding Japan and India as alert authorities added zero tools and zero bytes.

ENABLED_TOOLS=all                               # Use a preset
ENABLED_TOOLS=forecast,current,alerts,aqi       # Specific tools only
ENABLED_TOOLS=basic,+historical,+air_quality    # Add to a preset
ENABLED_TOOLS=all,-marine                       # Remove from a preset

Short aliases are supported: forecast, current, alerts, historical, status, search, aqi, marine, radar, lightning, and more.

Units & Localization

Output defaults to imperial (°F, mph, inHg, miles) and can be switched to metric (°C, km/h, hPa, km) server-wide or per request. Precedence: a per-call parameter beats a per-unit env override, which beats the WEATHER_UNITS system default.

WEATHER_UNITS=metric            # switch everything to metric
WEATHER_WIND_SPEED_UNIT=kn      # ...but wind in knots
WEATHER_TIME_FORMAT=24h         # 24-hour clock

Or per call — the AI can honor "in Celsius" on the fly:

{ "latitude": 47.6, "longitude": -122.3, "units": "metric" }
{ "latitude": 47.6, "longitude": -122.3, "wind_speed_unit": "kn", "pressure_unit": "hPa" }

Supported on get_forecast, get_current_conditions, and get_historical_weather. Wind accepts mph/kmh/ms/kn; pressure inHg/hPa. Domain-specialized readings (fire-weather heights, NWPS river gauge stage, and the marine tool's dual-unit wave output) keep their conventional units — NWPS stage is always feet. The Environment Agency river level is the exception: it is published in metres and follows the distance preference, so it renders in metres under km and feet under mi.

Other settings

For caching architecture details, see .github/CACHING.md.

Optional API keys

The default is the product. Every one of the 17 tools works with zero keys, zero signup, and zero cost — that is the configuration this project is built around and the one most people should use. If that's you, you can skip this section entirely.

Four optional keys each unlock one extra. Without them the corresponding tool still works; it just returns the keyless answer.

The NCEI and FIRMS keys are true free registrations. The two Google keys are not — each has a free usage tier, but Google requires a billing account with a payment method to issue them at all. That's why they aren't described as simply "free" anywhere in these docs, and why they stay strictly optional. They are separate variables on purpose: the recommended console restriction ties a key to one specific API, so a Pollen-restricted key cannot serve alerts and vice versa. If you prefer one unrestricted key, put the same string in both.

Standing key policy

So the "genuinely free" promise above stays meaningful, this project holds to three rules:

1. Optional keys must always have a usable free tier. A key that only makes

sense once you're paying doesn't belong here.

1. *No tool will ever require a key.* Every feature has a keyless path, even

if that path is "this data isn't available for your region".

1. *Features that would require a paid key are out of scope* unless there's

significant user demand for that specific service.

Optional dependency

Everything above installs by default and nothing here needs configuring — this section only matters if you want a smaller install.

One dependency, mqtt, exists for a single tool: get_lightning_activity streams live strikes from Blitzortung.org over MQTT, and nothing else in the server uses that transport. It is declared as an optionalDependency, so a normal install still includes it and lightning works exactly as described above. You can decline it:

npm install -g @dangahagan/weather-mcp --omit=optional

That installs 121 packages instead of 163 — 42 fewer, mqtt and its transitive tree.

What you give up, on both paths that reach lightning:

• get_lightning_activity returns an error naming the package and how to get it back, rather than

a result. It never reports "no strikes" — a missing dependency rendering as an all-clear on lightning is precisely the kind of confidently wrong safety answer this project treats as its worst failure.

• get_weather_summary still works, but its optional lightning section renders as

## lightning (unavailable) with the same message. Every other section is unaffected.

Nothing else changes: all 16 remaining tools behave identically, and get_lightning_activity still appears in tools/list.

To get lightning back, reinstall without the flag.

Source builds still use a plain `npm install`. TypeScript needs mqtt's bundled type declarations at build time even though the emitted server loads the package only when lightning is actually requested, so --omit=optional belongs to the published package, not to a build from a clone.

Coverage & Limitations

Being honest about what free public data can and can't do:

• A US hourly forecast and a US daily forecast come from the same NOAA product, and that product is human-adjusted. Its precipitation probability is a chance over the whole grid box, republished on the forecaster's cadence rather than a model run's, so at hourly resolution it can legitimately disagree with source="openmeteo"'s faster model view — neither is wrong. source="auto" picks NOAA on geography alone and now says so on every hourly response, with the **Updated:** header line showing when NOAA last published the grid. Daily forecasts are unaffected.
• European alerts are matched at country level — the keyless MeteoAlarm feeds carry no region polygons, so warnings for a large country may not affect the requested point; the output says so. Canadian alerts use a real bbox query with polygon-backed features.
• Philippine and Indonesian alerts are matched by the alert's own polygon, and Japanese alerts by JMA warning area, so a warning is shown only when it actually covers the requested point — finer than Europe's country-level matching. Japan resolves to one of the 143 areas JMA itself publishes warnings for; a point outside all of them, or one whose area is missing from the office's own bulletin, says so rather than reporting an all-clear. Indian alerts are currently country-level: SACHET publishes each alert's geometry from a separate endpoint that is not reliably reachable from servers, so Indian warnings are listed with an explicit note that they may not affect your exact location, exactly as Europe's are. Any alert whose geometry cannot be loaded is always listed rather than dropped — never silently treated as "not near you".
• Outside the US, Canada, Europe, India, the Philippines, Indonesia, and Japan, alerts need an optional GOOGLE_WEATHER_API_KEY; without one get_alerts says plainly that the region isn't covered rather than guessing. With a key, Google aggregates official national feeds for roughly 45 more territories — Australia, Brazil and Mexico among them, with Google's coverage page as the authoritative list. Matching is by provider polygon, so coverage alignment may not be exact and an empty answer means "no alerts found", not a guarantee of coverage; the output says so both ways. Alert text appears in the publisher's source language. The US, Canada, Europe, India, the Philippines, Indonesia, and Japan never contact Google — those authorities stay first choice, key or no key — and a key failure surfaces loudly rather than degrading to a possibly-false all-clear.
• International current conditions default to model-interpolated values at the exact coordinates. source="metar" returns a real instrument reading instead — but from the nearest airport, which may be tens of km away and up to an hour old. The output always names the station, its distance and bearing, and the observation age, so the tradeoff is visible rather than assumed. METAR coverage follows airports, so remote land and open ocean have real gaps.
• Historical data older than 7 days comes from reanalysis models (9–25km grid), not direct station observations, and trails real time by ~5 days.
• Non-US wildfire results are satellite heat detections, not managed incidents — no fire names, sizes, or containment percentages exist in the data, detections can include industrial heat sources or agricultural burns, and a clear result is not an all-clear (cloud cover hides fires; small or new fires evade detection). The output frames all of this explicitly. Keyless data covers the last 24 hours; an optional free FIRMS_MAP_KEY unlocks targeted queries and up to 5 days of detection history (day_range).
• Frostbite-risk and heat-stress (WBGT) lines are computed by this server from temperature, humidity, and wind — not agency-published ratings. The wind chill is the standard 2001 North American model; the frostbite time bands are adapted from Environment Canada's published categories and the WBGT is the Australian Bureau of Meteorology's simplified estimate, which assumes full sun and light wind and so can overestimate in shade or overcast. Exertion thresholds also genuinely shift with acclimatization. Treat both as context, not as an occupational-safety determination.
• Non-US fire weather is a Fosberg Fire Weather Index computed by this server from current model values — or, with source="metar", from the station's reported values — not an agency-published rating — US locations get NOAA's own Haines/grassland/red-flag indices instead. The output says which it is and defers to national fire authorities; its category bands are a project heuristic.
• Non-US river discharge is modeled, not observed, and has no official flood-stage thresholds — levels are shown relative to recent history and the forecast ensemble. The ~5km model grid means the reported channel may be a few km from the requested point; the output says so when it is.
• Pollen is Europe-only without a key: it rides the CAMS European model on the air-quality endpoint, which returns real grains/m³ in Europe and nothing anywhere else. An optional GOOGLE_POLLEN_API_KEY fills the gap for 65+ countries including the US, as a grass/tree/weed Universal Pollen Index (0–5) rather than per-species counts. Europe keeps the richer keyless data and never contacts Google.
• Marine data has limited coastal accuracy and is not suitable for navigation.
• Lightning coverage varies by region (community-operated detector network).
• Open-Meteo's fair-use limit is 10,000 requests/day; the built-in cache makes this hard to hit in normal use.

Development

npm run build          # Compile TypeScript
npm run dev            # Run in development mode
npm test               # Run all 4,838 tests
npm run test:coverage  # Coverage report
npm run audit          # Dependency vulnerability scan

Quality bar: TypeScript strict mode, no any types, 100% test coverage on critical utilities (cache, validation, unit conversion, errors), 100% pass rate, minimal runtime dependencies.

Project structure, patterns, and contribution guidance:

• CONTRIBUTING.md — how to contribute
• CLAUDE.md — architecture and development guide
• docs/README.md — complete documentation index

Security

• All inputs validated (coordinates, dates, ranges) before any API call
• Error messages sanitized — no internal details leak to output
• Zero secrets by design: no keys means nothing to steal or misconfigure
• Automated dependency scanning (npm audit + Dependabot), minimal dependency footprint
• Security policy and supported versions: see SECURITY.md

To report a vulnerability, see SECURITY.md.

Documentation

• [Examples](./examples/) — realistic sessions in cities around the world: prompt → assistant answer → verbatim server output
• [Tool Reference](./docs/TOOLS.md) — all 17 tools: parameters, examples, sample output
• [Client Setup](./docs/CLIENT_SETUP.md) — step-by-step for 8 MCP clients
• [Remote Hosting](./docs/REMOTE_HOSTING.md) — run weather-mcp-http behind your own OAuth authorization server
• [Error Handling](./docs/ERROR_HANDLING.md) — how failures are reported
• [Testing Guide](./docs/testing/TESTING_GUIDE.md) — manual testing procedures
• [Changelog](./CHANGELOG.md) — version history
• [Full documentation index](./docs/README.md)

Contributing

Contributions are welcome — this is a single-maintainer project and issues, PRs, and feedback genuinely help. See CONTRIBUTING.md.

License

MIT — free to use, modify, and distribute.

Weather data provided by NOAA, Open-Meteo, MET Norway, USGS, NIFC, RainViewer, and Blitzortung.org. This project is not affiliated with or endorsed by any of these providers. Do not rely on this server as your sole source for safety-critical decisions — always consult official warnings and forecasts.