Noaa Cdo Mcp Server

---

Tools

10 tools — 8 over the NOAA Climate Data Online (CDO) API v2, plus two over separate NCEI bulk-CSV corpora: severe-weather event search over the Storm Events Database, and disaster costs over Billion-Dollar Weather and Climate Disasters:

Tool	Description
noaa_climate_list_datasets	List available CDO datasets with IDs, names, and temporal coverage
noaa_climate_list_data_categories	List data category groups (Temperature, Precipitation, Wind, etc.)
noaa_climate_list_data_types	List specific measurement labels (TMAX, TMIN, PRCP, SNOW, etc.) by dataset or category
noaa_climate_list_location_categories	List the 12 location categories that scope location search
noaa_climate_find_locations	Search geographic locations by category (states, cities, counties, zip codes, climate regions), with an optional name filter
noaa_climate_find_stations	Search weather stations by location, bounding box, dataset, and data type
noaa_climate_get_station	Fetch full metadata for a single station by ID
noaa_climate_fetch_data	Fetch historical observation records for a dataset and date range
noaa_climate_search_storm_events	Search the NCEI Storm Events Database for one year — tornadoes, hail, floods, hurricanes, with damage, casualties, and narratives
noaa_climate_get_billion_dollar_disasters	Query NOAA's Billion-Dollar Weather and Climate Disasters — CPI-adjusted costs and deaths per disaster, or per-year totals by disaster class

noaa_climate_list_datasets

List all available NOAA CDO datasets — approximately 11 in total.

• Returns dataset IDs, names, data coverage fraction, and temporal range
• No required parameters — returns everything by default
• Optionally filter by data type, location, station, or date range
• Common datasets: GHCND (daily, 1763–present), GSOM (monthly), GSOY (annual), NORMAL_DLY/MLY/ANN/HLY (1981–2010 climate normals)
• Start here to orient before calling noaa_climate_fetch_data

---

noaa_climate_list_data_categories

List data category groups that organize related measurement types.

• ~41 categories including Temperature, Precipitation, Wind, Pressure, Sunshine, Sky cover, Weather Type
• Optionally filter by dataset, location, station, or date range
• Use before noaa_climate_list_data_types to narrow by measurement domain

---

noaa_climate_list_data_types

List specific measurement labels for a dataset or category.

• Hundreds of data types across all datasets
• Filter by dataset (e.g., GHCND) or category (e.g., TEMP) to narrow results
• Common GHCND types: TMAX (max temperature), TMIN (min temperature), PRCP (precipitation), SNOW (snowfall), SNWD (snow depth), AWND (average wind speed)
• Returns ID, name, coverage fraction, and date range per type

---

noaa_climate_list_location_categories

List the location categories that scope noaa_climate_find_locations — 12 in total.

• Returns category IDs (CITY, ST, CNTY, CNTRY, ZIP, US_TERR, CLIM_REG, CLIM_DIV, HYD_ACC, HYD_CAT, HYD_REG, HYD_SUB) and their names
• Call it when you do not know which locationCategoryId to pass
• Pagination and sort only — the CDO endpoint ignores dataset, location, station, and date filters, so none are offered

---

noaa_climate_find_locations

Search geographic locations by category.

• Category types: ST (US states, 51), CNTY (counties), CITY (cities), CNTRY (countries), ZIP (zip codes), US_TERR (US territories), CLIM_REG (NOAA climate regions), CLIM_DIV (climate divisions), hydrological categories — noaa_climate_list_location_categories returns the authoritative set
• Use locationCategoryId=ST to list all states in one call
• nameContains gives the name search the CDO API lacks: the server enumerates the requested category and matches the substring case-insensitively, so locationCategoryId=CITY with nameContains=seattle resolves a city in one call. It is a size rule, not a category list — the category must hold at most 4,000 locations, which is every category but ZIP (30,415), and a datasetId or datacategoryId filter can bring a larger one back under the limit. Past it, page alphabetically with sortField=name
• Returns location IDs (FIPS:37, CITY:US530018, ZIP:98101) used in station search and data queries

---

noaa_climate_find_stations

Search weather observation stations.

• Filter by location ID, bounding box (lat/lon), dataset, data type, and date range
• Returns station IDs, names, coordinates, elevation, and data coverage dates
• A station must have data for the dataset and date range you want — pass datasetId and date range to ensure compatibility
• Common station ID formats: GHCND:USW00024233, COOP:010008
• Station IDs returned here feed directly into noaa_climate_fetch_data

---

noaa_climate_get_station

Fetch full metadata for a single weather station by ID.

• Returns name, coordinates (decimal degrees), elevation, and full data coverage date range
• Use to verify a station before querying data, or to check its temporal coverage
• Mirrors the noaa://stations/{stationId} resource as a direct lookup

---

noaa_climate_fetch_data

Fetch historical observation records from a NOAA CDO dataset.

• Requires datasetId, startDate, and endDate; optionally scoped by station, location, and data type
• Date range limits: sub-daily, daily, and radar datasets (GHCND, PRECIP_15, PRECIP_HLY, NORMAL_DLY, NORMAL_HLY, NEXRAD2, NEXRAD3) — 1 year max per request; monthly and annual datasets (GSOM, GSOY, NORMAL_MLY, NORMAL_ANN) — 10 years max
• Unit selection: strongly recommended — pass units=metric (SI) or units=standard (Fahrenheit/inches). Without it, GHCND values are raw tenths-of-unit integers (TMAX=256 = 25.6°C, PRCP=12 = 1.2mm); GSOM/GSOY are already scaled
• Climate normals: for any NORMAL_* dataset, use startDate=2010-01-01 and endDate=2010-12-31 — that is the API proxy year regardless of which 30-year period is described
• Returns flat tuples of { date, datatype, station, value, attributes } with pagination metadata

---

noaa_climate_search_storm_events

Search the NCEI Storm Events Database — a different NOAA corpus from the CDO tools above.

• Discrete severe-weather events (tornado, hail, flood, hurricane, winter storm, heat, and every other NWS Storm Data type) rather than station observations, back to 1950
• Returns event type, state and county/zone, begin and end times, magnitude, tornado F/EF scale with track length and width, direct and indirect deaths and injuries, property and crop damage, and the episode and event narratives
• No token required — this corpus is published as bulk CSV, not through CDO, so NOAA_CDO_TOKEN is irrelevant to this tool
• year is required. NCEI publishes one gzip file per year (~12 MB, ~70k events for a recent year), so an unscoped search would download every year back to 1950
• state takes the full name NCEI writes — "FLORIDA", not "FL". eventType is matched case-insensitively against the exact NWS label ("Tornado", "Flash Flood", "Hurricane (Typhoon)"); a miss comes back with the labels that year actually contains
• Damage is honest about what NCEI reported. Values arrive as magnitude-suffixed strings ("75.00K", "1.20M", "1.00B") and are returned as both the raw cell and a parsed dollar amount. An unreported figure — about a fifth of a recent year — is omitted entirely rather than reported as 0, so it can never be read as confirmed zero damage. minDamageInUsd therefore excludes those rows and reports how many it dropped
• Filenames are discovered, never constructed. Each year's file carries a publish-date suffix that changes when NCEI republishes it, so the tool reads the directory index every time its cache lapses
• The server caches two years of compressed bytes for six hours — under 30 MB, since a bundle runs 12 MB for a recent year and 15 MB for the largest (2011). Each search streams the decompression, so the ~70 MB decompressed form is never materialized. That bounds what is retained, not peak memory: the transient chunks still cost headroom, and a cold full-year 2024 scan measured 129 MB RSS at baseline against a 269 MB peak

---

noaa_climate_get_billion_dollar_disasters

Query NOAA/NCEI's Billion-Dollar Weather and Climate Disasters — the curated record of US weather and climate disasters whose damage passed $1 billion.

• Two shapes from one tool: individual disasters by default (name, class, span, CPI-adjusted and unadjusted cost, deaths), or summary=true for per-year counts and costs by disaster class plus an All Disasters total
• Seven disaster classes, written exactly as NCEI writes them: Drought, Flooding, Freeze, Severe Storm, Tropical Cyclone, Wildfire, Winter Storm. disasterType rejects any other spelling rather than coercing it
• No token required — this corpus is published as static CSV, not through CDO
• Every cost is in whole US dollars. NCEI does not use one unit across these exports: the per-event file states millions, the national per-year file states billions, and a per-state per-year file states millions again. The server reads the unit each file declares in its own preamble, converts once, and reports what it read back as declaredCostUnit. Conflating the two would misreport by a factor of 1,000 while still looking plausible — Hurricane Helene is 78721 in a millions file, which is $78.7 billion, not $78,721 billion
• Coverage is whatever NCEI has finished assessing, not the current calendar year — coveredYears reports the span actually present (1980–2024 as of writing). A query for this year returns nothing rather than an error
• startYear/endYear match by overlap, so a disaster running across a New Year is returned from either side of it
• A state scope reads NCEI's per-state exports and behaves differently in two ways. Its per-event rows are national disasters that reached that state and carry the national cost, never a state share — summing states double-counts, which the response says for itself with costBasis: "national". Its per-year rows carry a binned cost range (costRangeInUsd) instead of the point estimate and 75/90/95% confidence bands the national export publishes
• Not every two-letter code has an export: the 50 states, DC, PR, VI, and GU do; AS and MP do not, and a code without one fails with unknown_state rather than silently falling back to national totals

---

Resources

Type	Name	Description
Resource	noaa://datasets	All CDO datasets with IDs and temporal coverage — injectable context for orienting an agent before querying data
Resource	noaa://stations/{stationId}	Station metadata by ID — name, coordinates, elevation, and data coverage date range

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

NOAA CDO-specific:

• Full CDO API v2 coverage — datasets, data categories, data types, locations, stations, and observations
• Client-side date range validation with per-dataset limits enforced before hitting the API
• Unit normalization via the CDO units parameter — avoids raw tenths-of-unit integer confusion
• CDO's own rejection message is recovered and surfaced: an over-long date range, a malformed date, a missing parameter, and an over-large limit each report the reason CDO gave, instead of an identical bare status line
• Retry with exponential backoff for transient API failures

Agent-friendly output:

• Paginated results across all list and search tools — limit, offset, and total count in every response
• Station and dataset IDs flow naturally between tools — find a location, find stations in it, fetch data from those stations
• Structured error contracts with reason codes and recovery hints — agents can branch on data, not string parsing
• Dataset and station resources for injectable, zero-fetch context

Getting started

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

Configuration

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

Variable	Description	Default
NOAA_CDO_TOKEN	Required. NOAA CDO API token — obtain free at ncdc.noaa.gov/cdo-web/token	—
MCP_TRANSPORT_TYPE	Transport: stdio or http	stdio
MCP_HTTP_PORT	HTTP server port	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path where the MCP server is mounted	/mcp
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments	none
MCP_AUTH_MODE	Authentication: none, jwt, or oauth	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.)	info
MCP_GC_PRESSURE_INTERVAL_MS	Opt-in Bun-only forced-GC pressure loop (ms). Try 60000 if heap growth is observed under sustained HTTP load.	0 (disabled)
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	Enable OpenTelemetry	false

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
  

Project structure

Directory	Purpose
src/mcp-server/tools	Tool definitions (*.tool.ts). Ten tools across datasets, locations, stations, observations, storm events, and disaster costs.
src/mcp-server/resources	Resource definitions. Datasets catalog and station metadata resources.
src/services/cdo	CDO HTTP client with retry, backoff, camelCase→lowercase parameter translation, and recovery of CDO's own rejection message.
src/services/csv	Incremental RFC 4180 CSV reader shared by the two NCEI bulk-CSV corpora.
src/services/storm-events	NCEI Storm Events bulk-CSV client — filename discovery, streamed decompression, damage parsing.
src/services/billion-dollar-disasters	NCEI Billion-Dollar Disasters client — declared-unit resolution and conversion to whole US dollars.
src/config	Server-specific environment variable parsing and validation with Zod.
tests/	Unit and integration tests, mirroring the src/ 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 and pull requests 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.