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)

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
• 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 is required (1950 through the current partial year); filter by episodeId (exact digit string from a returned event; blank means unset), state (the full NCEI name, e.g. "FLORIDA"), eventType, month, and minDamageInUsd; limit 1–100 (default 50) with offset
• Each distinct episode narrative appears once in episodeNarratives, linked from events by episodeNarrativeRef; individual eventNarrative text stays on each event. 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
• Coverage runs 1980 through the last year NCEI has finished assessing (coveredYears), not the current calendar 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
• 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, missing parameter, or over-large limit 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; CDO metadata stays absent when upstream omits it or includemetadata=false. Coordinates and coverage retain upstream precision; coverage text uses raw fractions labeled 0–1.
• 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 all requests.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd noaa-climate-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

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

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

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

Running the server

Local development

• Build and run the production version:

  shCopy

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

• Run checks and tests:

  shCopy

  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.