io.github.cyanheads/noaa-cdo-mcp-server

@cyanheads/noaa-climate-mcp-server

Search NOAA climate stations and datasets, fetch historical weather observations via MCP. STDIO or Streamable HTTP.

10 Tools • 2 Resources

Public Hosted Server: https://noaa-climate.caseyjhand.com/mcp

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

Capability reference

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 { date, datatype, station, value, attributes } records plus an effectiveQuery echo; date_range_exceeded names the latest maxEndDate CDO will accept
• units: "metric" or "standard" is strongly recommended — without it, GHCND values are raw tenths-of-unit integers (e.g. TMAX=256 is 25.6°C)

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 normalization via CDO's units parameter avoids raw tenths-of-unit integer confusion
• 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

Public Hosted Instance

A public instance is available at https://noaa-climate.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "streamable-http",
      "url": "https://noaa-climate.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/noaa-climate-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NOAA_CDO_TOKEN": "your-token-here"
      }
    }
  }
}

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "NOAA_CDO_TOKEN=your-token-here", "ghcr.io/cyanheads/noaa-climate-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NOAA_CDO_TOKEN=your-token-here bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js ≥24.0.0).
• A free NOAA CDO API token — required for CDO requests; Storm Events and Billion-Dollar Disasters need no token.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/noaa-climate-mcp-server.git

1. Navigate into the directory:

cd noaa-climate-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set required vars

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

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  bun 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 devcheck
bun run test

License

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