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.

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.

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.
• Fully open source — MIT licensed, readable TypeScript, 2,077 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, and the official national warnings of 38 European countries via EUMETNET MeteoAlarm — shown unmodified, with the issuing service credited. 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.
• 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.

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.

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.
• 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).
• 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.
• 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,077 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
• Independent security audit: see docs/development/SECURITY_AUDIT.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.