noaa-climate-mcp-server

<div align="center">
  <h1>@cyanheads/noaa-climate-mcp-server</h1>
  <p><b>Search NOAA climate stations and datasets, fetch historical weather observations via MCP. STDIO or Streamable HTTP.</b>
  <div>10 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.6.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/noaa-climate-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.30.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/noaa-climate-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/noaa-climate-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/noaa-climate-mcp-server/releases/latest/download/noaa-climate-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=noaa-climate-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbm9hYS1jbGltYXRlLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7Ik5PQUFfQ0RPX1RPS0VOIjoieW91ci10b2tlbi1oZXJlIn19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22noaa-climate-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnoaa-climate-mcp-server%22%5D%2C%22env%22%3A%7B%22NOAA_CDO_TOKEN%22%3A%22your-token-here%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://noaa-climate.caseyjhand.com/mcp](https://noaa-climate.caseyjhand.com/mcp)

</div>

---

## 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 f