noaa-climate-mcp-server: Instructions file for Claude Code

Developer Protocol

Server: noaa-climate-mcp-server Version: 0.6.2 Framework: @cyanheads/mcp-ts-core ^0.12.3 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.0.0 Zod: ^4.4.3

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

Domain

NOAA Climate Data Online (CDO) API v2 — historical weather data — plus two separate NCEI bulk-CSV corpora: the Storm Events Database and Billion-Dollar Weather and Climate Disasters. 10 tools, 2 resources:

• noaa_climate_list_datasets — list available CDO datasets
• noaa_climate_list_data_categories — list measurement category groups
• noaa_climate_list_data_types — list measurement labels by dataset or category
• noaa_climate_list_location_categories — list the location categories that scope location search
• noaa_climate_find_locations — search geographic locations by category, with an optional client-side name filter
• noaa_climate_find_stations — search weather stations by location, bounding box, dataset
• noaa_climate_get_station — fetch full metadata for a single station
• noaa_climate_fetch_data — fetch historical observations with date range validation and unit selection
• noaa_climate_search_storm_events — search NCEI Storm Events for one year (severe-weather events, damage, casualties, narratives)
• noaa_climate_get_billion_dollar_disasters — query NCEI Billion-Dollar Weather and Climate Disasters, per disaster or per year
• noaa://datasets resource — all CDO datasets as injectable context
• noaa://stations/{stationId} resource — station metadata by ID

Services:

• src/services/cdo/cdo-service.ts — HTTP client with retry/backoff, NOAA_CDO_TOKEN header auth.
• src/services/storm-events/storm-events-service.ts — NCEI bulk CSV. No token, no JSON envelope, no resolveCollectionTotal(). Resolves each year's _c<publishDate>-suffixed filename from the live directory index (it is not constructible), decompresses explicitly (the files carry no Content-Encoding), and streams a year through the shared CSV reader so the decompressed ~70 MB is never held. Caches the listing and two years of compressed bytes for six hours. Damage parsing lives in damage.ts — an empty cell is "not reported", never 0.
• src/services/billion-dollar-disasters/billion-dollar-disasters-service.ts — NCEI Billion-Dollar Disasters. No token, four small static CSVs (per-event and per-year, national and per-state), each opening with preamble lines ahead of the header. Each file declares its own cost unit and they differ — millions for per-event, billions for the national per-year, millions again for a per-state per-year — so the unit is parsed from the file's preamble and applied at one site, toUsd(), converting everything to whole US dollars. An unrecognized or absent unit is malformed_export, never a guess.
• src/services/csv/csv-stream-reader.ts — the RFC 4180 reader both bulk-CSV services parse with.