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, 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 — 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, 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. (Three optional keys add extras if you want them; the default configuration needs none.)
• Fully open source — MIT licensed, readable TypeScript, 2,510 tests. Audit it, fork it, fix it.
• Privacy-respecting — your queries go directly from your machine to public weather APIs. No middleman server, no telemetry.
• 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:

Default preset: with no configuration, the server exposes 17 tools led by 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 pick; it just works.
• 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, and the national CAP feeds of India (NDMA SACHET), the Philippines (PAGASA) and Indonesia (BMKG) — 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). 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.

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 18+. No API keys, tokens, or accounts needed — see Optional API keys for the three that add optional extras.

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.

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.

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:

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, river gauge stage, and the marine tool’s dual-unit wave output) keep their conventional units.

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.
2. 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”.
3. Features that would require a paid key are out of scope unless there’s significant user demand for that specific service.

Coverage & Limitations

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

• 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, so a warning is shown only when it actually covers the requested point — finer than Europe’s country-level matching. 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, and Indonesia, 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, Japan, 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, and Indonesia 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, 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 2,510 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 — realistic sessions in cities around the world: prompt → assistant answer → verbatim server output
• Tool Reference — all 17 tools: parameters, examples, sample output
• Client Setup — step-by-step for 8 MCP clients
• Error Handling — how failures are reported
• Testing Guide — manual testing procedures
• Changelog — version history
• Full documentation index

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, 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.