Noaa Climate Mcp Server

Overview

Historical weather and climate records from NOAA: station observations from Climate Data Online, the Storm Events Database, and Billion-Dollar Weather and Climate Disasters. Find stations, pull observations in the units you want, and look up storm damage or disaster costs.

Tools

Resources

Agent skill

noaa-climate-guide covers historical comparisons, coverage checks, observation quality, and storm-to-station investigation. It ships with plugin, npm, Docker, and MCPB installs and is served through the MCP Skills extension and a skill resource alongside the two data resources.

Capability reference

Every stationId input, including the station resource, trims surrounding whitespace and uppercases IDs. Bare 11-character GHCN IDs (USW00024233) become GHCND:USW00024233. Namespaced IDs such as COOP:454769, NEXRAD:KATX, and unfamiliar nonempty namespace/payload pairs remain accepted; ambiguous bare IDs are rejected. Tools disclose changes in a notice; the resource returns the canonical station ID. Syntax does not establish that a station exists.

noaa_climate_list_datasets _tool

• No required inputs; optional data type, location, station, and date-range filters; limit 1–1000 (default 25) with offset, sortable by id, name, mindate, maxdate, or datacoverage
• Returns each dataset's ID, name, and date span — GHCND (daily, 1763–present), GSOM (monthly), GSOY (annual), NORMAL_DLY/MLY/ANN/HLY (1981–2010 normals)
• Date filters use inclusive coverage overlap: maxdate >= startDate and mindate <= endDate for each supplied bound. The complete catalog matching the other filters is retrieved before filtering and pagination; totals describe that filtered view.

noaa_climate_list_data_categories _tool

• Optional dataset, location, station, and date-range filters; limit 1–1000 (default 25) with offset, sortable by id or name
• Returns the 42 measurement categories (Temperature, Precipitation, Wind, Pressure, Sunshine, and more), whose IDs narrow noaa_climate_list_data_types as datacategoryId

noaa_climate_list_data_types _tool

• Filter by datasetId (e.g. GHCND) or datacategoryId (e.g. TEMP); limit 1–1000 (default 25) with offset
• Returns the datatype IDs noaa_climate_fetch_data takes — common GHCND types are TMAX, TMIN, PRCP, SNOW, SNWD, AWND — with coverage and date range when CDO carries them

noaa_climate_list_location_categories _tool

• Pagination and sort only: limit 1–1000 (default 25) with offset, sortable by id or name
• Returns the 12 category IDs noaa_climate_find_locations accepts as locationCategoryId: CITY, ST, CNTY, CNTRY, ZIP, US_TERR, CLIM_REG, CLIM_DIV, HYD_ACC, HYD_CAT, HYD_REG, HYD_SUB

noaa_climate_find_locations _tool

• locationCategoryId scopes the search (e.g. ST returns all 51 states); optional datasetId, datacategoryId, and date-range filters; limit 1–1000 (default 25) with offset
• Returns the location IDs noaa_climate_find_stations and noaa_climate_fetch_data take — FIPS:37, CITY:US530018, ZIP:98101
• nameContains adds a case-insensitive name match within one category of at most 4,000 locations (every category but ZIP); it fails as name_filter_requires_category without a category and name_filter_category_too_large past the cap

noaa_climate_find_stations _tool

• Filter by locationId, extent (lat/lon bounding box), datasetId, datatypeId (array), and date range; limit 1–1000 (default 25) with offset
• extent is minLat,minLon,maxLat,maxLon: four finite signed decimal or scientific numbers, with surrounding whitespace allowed, latitude within ±90 and longitude within ±180. Equal coordinates work; reversed axes return no matches and are forwarded unchanged, without antimeridian wrapping.
• Returns station IDs (GHCND:USW00024233, COOP:010008), names, coordinates, elevation, and data-coverage dates — the IDs feed noaa_climate_fetch_data as stationId

noaa_climate_get_station _tool

• Single required input: stationId, from noaa_climate_find_stations; the tool form of the noaa://stations/{stationId} resource
• Returns name, coordinates, elevation, and the full data-coverage date range; fails as not_found when a well-formed ID resolves to nothing

noaa_climate_fetch_data _tool

• Requires datasetId, startDate, endDate; optional stationId, locationId, datatypeId arrays. The span cap is 1 year for GHCND, PRECIP_15, PRECIP_HLY, NORMAL_DLY, NORMAL_HLY, NEXRAD2, NEXRAD3 and 10 years for GSOM, GSOY, NORMAL_MLY, NORMAL_ANN; any NORMAL_* dataset takes startDate=2010-01-01 / endDate=2010-12-31
• Returns flat observation records plus an effectiveQuery echo; date_range_exceeded names the latest maxEndDate CDO will accept. The encoded query ceiling is 4000 characters; longer queries fail as validation_error before any request. Reduce stationId, locationId, and datatypeId filters and make separate calls. Filters are never discarded or automatically split.
• Request units: "metric" or "standard". Omission preserves NOAA's raw values and adds dataset-specific guidance, including on empty pages. Examples: GHCND TMAX/TMIN use tenths °C, PRCP tenths mm, and SNOW/SNWD whole mm; GSOM/GSOY temperature and precipitation use °C/mm; NORMAL_* temperature normals use tenths °F and precipitation normals hundredths inches; PRECIP_HLY HPCP and PRECIP_15 QPCP use hundredths inches. Units and scale depend on datatype; these examples do not describe wind, direction, counts, percentages, or every snow datatype. See NOAA's dataset documentation.
• PRECIP_HLY HPCP and PRECIP_15 QPCP missing sentinels become missing: true with value omitted: 99999 without units, 999.99 standard, or 25399.75 metric. Rows, raw attributes, order, totals, and offsets remain intact. Zero, trace, and accumulation-end measurements remain values; flags alone do not mark a row missing. A notice counts missing observations on this page.
• GHCND attributes remain raw and are also decoded as flags: { measurement, quality, source, observationTime }. Explicit blank slots and leading-zero times are preserved; absent trailing positions remain omitted. A nonblank quality means the observation failed a quality check. A notice counts those rows on this page; numeric values remain available for callers to decide how to aggregate them. Other datasets retain their raw attributes without GHCND decoding. See GHCND's flag layout.

noaa_climate_search_storm_events _tool

• No token required; year selects one export (1950 through the current partial year); filter by episodeId (exact digit string from a returned event; whitespace is trimmed, blank means unset, leading zeros remain significant), state (the full NCEI name, e.g. "FLORIDA"), eventType, month, startDate/endDate, and minDamageInUsd; page ceiling 100 (default 50) with offset
• Optional startDate/endDate are real YYYY-MM-DD dates and match inclusive event-span overlap before damage accounting, totals, and pagination. One-sided, equal, and cross-year intervals work; only year selects the export. Active date bounds exclude missing, invalid, or reversed source spans; without bounds those rows remain visible. appliedDateRange echoes supplied bounds on both surfaces. Reversed request dates fail as invalid_date_range before downloading.
• Each distinct episode narrative appears once in episodeNarratives, linked from events by episodeNarrativeRef; individual eventNarrative text stays on each event. Rendered narratives preserve literal punctuation and line breaks. Optional local ISO beginDate/endDate values can feed CDO date filters alongside the unchanged NCEI date-time and timezone fields.
• Damage arrives as the raw magnitude-suffixed string ("1.20M") and a parsed dollar amount, omitted rather than zeroed when NCEI reported none; a zero-match response names the event types and states the year contains
• Fails as year_unavailable when NCEI publishes no file for the year, and malformed_export when a downloaded file is not the expected table

noaa_climate_get_billion_dollar_disasters _tool

• Individual disasters by default, or summary=true for per-year counts and costs by disaster class; filter by startYear/endYear, disasterType (one of seven NCEI classes), minCostInUsd, and state (two-letter postal code); limit 1–100 (default 50) with offset
• Every cost is whole US dollars whatever unit the export declares (echoed as declaredCostUnit); a state scope reports national costs (costBasis: "national") and binned per-year costRangeInUsd
• NOAA retired the product after 2024; the 1980–2024 archive remains available with no later years added. coveredYears reports the span actually present in the selected export. Every successful response carries this archive notice alongside any clamp or paging guidance.
• CPI-adjusted costs preserve the archived export’s adjustment; the server does not rebase them to current prices or infer a CPI base year.

noaa://datasets _resource

• All CDO datasets as application/json — IDs, names, temporal coverage
• Equivalent to noaa_climate_list_datasets with no filters and a high limit — injectable, zero-fetch context

noaa://stations/{stationId} _resource

• stationId from noaa_climate_find_stations; the resource form of noaa_climate_get_station
• Returns station metadata; fails as not_found when a well-formed ID resolves to nothing

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

NOAA-specific:

• Full CDO API v2 coverage — datasets, data categories, data types, locations, stations, and observations — plus two separate NCEI bulk-CSV corpora requiring no token: severe-weather events (Storm Events Database) and billion-dollar disaster costs
• Client-side date-range validation enforced per dataset before hitting the API, reporting the exact upstream limit back to the caller
• Discovery date intervals reject startDate > endDate before any request, with validation_error and a hint to swap the values. Equal and single-ended dates remain valid; compact YYYYMMDD, unpadded dashed dates, and supported second-precision datetime forms are normalized for comparison.
• Unit conversion via CDO's units parameter, with datatype-qualified guidance when raw values are requested
• CDO's own rejection message is recovered and surfaced — an over-long date range, malformed date, or missing parameter reports the reason CDO gave instead of a bare status line
• Billion-Dollar Disasters costs are converted to whole US dollars from whichever unit each NCEI export declares in its own preamble, since the unit differs by export

Agent-friendly output:

• Paginated results across every list and search tool — zero-based offset in inputs and returned metadata. Locally filtered dataset and location views synthesize metadata from the filtered results; other CDO pages preserve absent upstream metadata. Coordinates and coverage retain upstream precision; coverage text uses raw fractions labeled 0–1.
• Positive integer read limits are clamped to the page ceiling: 1000 for CDO, 100 for Storm Events and Billion-Dollar Disasters. A notice names the requested and applied limits alongside any empty-page or exhaustion guidance; use the applied limit to advance offset. Each clamp is logged and counted as noaa.pagination.limit_clamped.
• Station, location, and dataset IDs flow naturally between tools — find a location, find stations in it, fetch data from those stations
• Structured error contracts with typed reason codes and recovery hints — agents branch on data, not string parsing
• Damage and cost fields are honest about upstream gaps — an unreported NCEI figure is omitted rather than reported as a confirmed zero

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http noaa-climate-mcp-server https://noaa-climate.caseyjhand.com/mcp

Or run it locally:

claude mcp add noaa-climate-mcp-server -e NOAA_CDO_TOKEN=your-token-here -- npx -y @cyanheads/noaa-climate-mcp-server

For other clients, add this to the MCP config file:

{  "mcpServers": {    "noaa-climate-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/noaa-climate-mcp-server"],      "env": { "NOAA_CDO_TOKEN": "your-token-here" }    }  }}

Get a free NOAA CDO API token for CDO requests; Storm Events and Billion-Dollar Disasters need no token. For Docker or a source build, see Running the server.

Configuration

Server-specific configuration uses Zod schemas in src/config/server-config.ts. The page-limit policy is validated at startup; the CDO token is required when a CDO request runs. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Prerequisites

• Bun v1.4.0 or higher (or Node.js ≥24.0.0).
• A free NOAA CDO API token for CDO requests; the two bulk corpora need no token.

Source installation

git clone https://github.com/cyanheads/noaa-climate-mcp-server.gitcd noaa-climate-mcp-serverbun installcp .env.example .env# Set NOAA_CDO_TOKEN in .env for CDO requests.

Local development

• Build and run the production version:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:http# orbun run start:stdio

• Run checks and tests:

  sh

  bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suitebun run test:live # Opt-in: resolves every documented example identifier against the live CDO API

Docker

docker build -t noaa-climate-mcp-server .docker run --rm -e NOAA_CDO_TOKEN=your-token-here -p 3010:3010 noaa-climate-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/noaa-climate-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays
• Wrap external API calls as validate raw → normalize to domain types → return the output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.