noaa-climate-mcp-server

Find NOAA Climate Locations

noaa_climate_find_locations

Read-only

Search for geographic locations by category (CITY, ST, CNTY, CNTRY, ZIP, CLIM_REG, etc.). Returns location IDs used in station search and data queries. Without locationCategoryId, returns all location types; noaa_climate_list_location_categories lists the valid values. Use locationCategoryId=ST to list US states (51 entries — small enough to retrieve completely). To find a location by name, pass nameContains alongside locationCategoryId — the CDO API has no name parameter, so this server enumerates the category and matches the substring itself. It works for any category under the size limit stated on nameContains, which is every category except ZIP; a datasetId or datacategoryId filter can bring a category back under that limit. For a category still too large, sort alphabetically with sortField=name and page through results. Location IDs: states as FIPS:37 (NC), cities as CITY:US530018 (Seattle), zip codes as ZIP:98101, countries as FIPS:US. Obtain location IDs here, then pass them to noaa_climate_find_stations or noaa_climate_fetch_data.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of results to return (1–1000). Defaults to 25. Larger positive integers are clamped to 1000 with a notice unless NOAA_CLAMP_LIMITS=false.
`offset`	No	Zero-based index of the first result to return for pagination. Defaults to 0.
`endDate`	No	Filter to locations with data on or before this ISO date (YYYY-MM-DD). Optional.
`datasetId`	No	Filter to locations covered by this dataset (e.g., "GHCND"). Optional.
`sortField`	No	Sort results by this field. Use name with sortOrder=asc to browse alphabetically when searching for a specific city or location name. Optional.
`sortOrder`	No	Sort direction. Optional; defaults to asc.
`startDate`	No	Filter to locations with data on or after this ISO date (YYYY-MM-DD). Optional.
`nameContains`	No	Case-insensitive substring match on the location name. The CDO API has no name parameter, so this server applies the match itself, across the whole category rather than one page — which bounds it to a category holding at most 4000 locations. Requires locationCategoryId; adding datasetId or datacategoryId narrows a category that is otherwise too large. Example: locationCategoryId="CITY" with nameContains="seattle". Optional.
`datacategoryId`	No	Filter to locations with this data category (e.g., "TEMP"). Optional.
`locationCategoryId`	No	Category filter. Use ST for states (51 entries), CNTY for counties, CITY for cities (large set — thousands of entries), CNTRY for countries, ZIP for zip codes, US_TERR for US territories, CLIM_REG for NOAA climate regions, CLIM_DIV for climate divisions, HYD_ACC/HYD_CAT/HYD_REG/HYD_SUB for hydrological categories. Call noaa_climate_list_location_categories when you do not know which category to use — it returns the authoritative set. Optional — omit to return all location types.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Page-limit adjustment and empty or exhausted-page guidance. Omitted when no guidance applies.
`results`	No	Matching locations.
`metadata`	No	Pagination metadata. Present when the API returns it.
`exhausted`	No	True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.
`totalCount`	No	Total number of matching locations before the page limit.
`appliedNameFilter`	No	The nameContains value this response was filtered by. Present only when nameContains was supplied; every count below then describes the filtered set, not the whole category.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 23, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum number of results to return (1–1000). Defaults to 25."New value: +"Maximum number of results to return (1–1000). Defaults to 25. Larger positive integers are clamped to 1000 with a notice unless NOAA_CLAMP_LIMITS=false."

changedInput schema / properties / limit / maximum

Previous value: -1000New value: +9007199254740991

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown datacategoryId or datasetId). `name_filter_requires_category`: nameContains was supplied without a locationCategoryId to scope the enumeration. `name_filter_category_too_large`: The requested locationCategoryId holds more locations than nameContains can enumerate. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: startDate is after endDate, or a filter parameter is not recognized by NOAA CDO (e.g., unknown datacategoryId or datasetId). `name_filter_requires_category`: nameContains was supplied without a locationCategoryId to scope the enumeration. `name_filter_category_too_large`: The requested locationCategoryId holds more locations than nameContains can enumerate. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no locations matched — echoes applied filters and suggests how to broaden."New value: +"Page-limit adjustment and empty or exhausted-page guidance. Omitted when no guidance applies."

Changed1 schema field changedOct 19, 2026

changedOutput schema / properties / metadata / properties / resultset / properties / offset / description

Previous value: -"Starting index of this page: 1-based as returned by the NOAA CDO API, or the zero-based offset you supplied when appliedNameFilter is present."New value: +"Zero-based starting index of this page, echoing the requested offset."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown datacategoryId or datasetId). `name_filter_requires_category`: nameContains was supplied without a locationCategoryId to scope the enumeration. `name_filter_category_too_large`: The requested locationCategoryId holds more locations than nameContains can enumerate. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "service_unavailable",
+            "rate_limited",
+            "upstream_auth_failed",
+            "validation_error",
+            "name_filter_requires_category",
+            "name_filter_category_too_large"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "results",
-  "totalCount"
-]

Changed6 schema fields changedAug 18, 2026

changedInput schema / properties / locationCategoryId / description

Previous value: -"Category filter. Use ST for states (51 entries), CNTY for counties, CITY for cities (large set — thousands of entries), CNTRY for countries, ZIP for zip codes, CLIM_REG for NOAA climate regions, CLIM_DIV for climate divisions, HYD_ACC/HYD_CAT/HYD_REG/HYD_SUB for hydrological categories. Optional — omit to return all location types."New value: +"Category filter. Use ST for states (51 entries), CNTY for counties, CITY for cities (large set — thousands of entries), CNTRY for countries, ZIP for zip codes, US_TERR for US territories, CLIM_REG for NOAA climate regions, CLIM_DIV for climate divisions, HYD_ACC/HYD_CAT/HYD_REG/HYD_SUB for hydrological categories. Call noaa_climate_list_location_categories when you do not know which category to use — it returns the authoritative set. Optional — omit to return all location types."

addedInput schema / properties / nameContains

Added value: +{
+  "description": "Case-insensitive substring match on the location name. The CDO API has no name parameter, so this server applies the match itself, across the whole category rather than one page — which bounds it to a category holding at most 4000 locations. Requires locationCategoryId; adding datasetId or datacategoryId narrows a category that is otherwise too large. Example: locationCategoryId=\"CITY\" with nameContains=\"seattle\". Optional.",
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / appliedNameFilter

Added value: +{
+  "description": "The nameContains value this response was filtered by. Present only when nameContains was supplied; every count below then describes the filtered set, not the whole category.",
+  "type": "string"
+}

changedOutput schema / properties / metadata / properties / resultset / properties / count / description

Previous value: -"Total number of matching locations."New value: +"Total number of matching locations — the post-filter match count when appliedNameFilter is present."

changedOutput schema / properties / metadata / properties / resultset / properties / offset / description

Previous value: -"1-based starting index of this page as returned by the NOAA CDO API."New value: +"Starting index of this page: 1-based as returned by the NOAA CDO API, or the zero-based offset you supplied when appliedNameFilter is present."

changedOutput schema / properties / results / items / properties / id / description

Previous value: -"Location ID (e.g., FIPS:37, CITY:US530031, ZIP:98101)."New value: +"Location ID (e.g., FIPS:37, CITY:US530018, ZIP:98101)."

Changed6 schema fields changedAug 18, 2026

addedInput schema / properties / datacategoryId / minLength
```
Added value: +1
```
addedInput schema / properties / datasetId / minLength
```
Added value: +1
```

addedInput schema / properties / endDate / pattern

Added value: +"^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$"

addedInput schema / properties / locationCategoryId / minLength
```
Added value: +1
```

addedInput schema / properties / startDate / pattern

Added value: +"^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$"

addedOutput schema / properties / exhausted

Added value: +{
+  "description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
+  "type": "boolean"
+}

First observedJun 22, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond readOnlyHint/openWorldHint by disclosing a non-obvious implementation quirk: the CDO API has no name parameter, so the server enumerates the entire category and substring-matches locally, bounding nameContains to categories of at most 4000 locations. It also flags ZIP as the one category that cannot be name-searched and offers a sort+paginate fallback, which materially changes how an agent should plan calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the location-ID formats are front-loaded, and most sentences carry operational guidance. There is mild redundancy — the 4000-entry ceiling on nameContains is stated once in the description and again as 'under the size limit stated on nameContains', and the ZIP exception is explained twice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, zero-required search tool this covers the full agent workflow: category choice, name search workaround with its size limit, pagination fallback, concrete ID formats (FIPS:37, CITY:US530018, ZIP:98101, FIPS:US), and the downstream tools. Return-value detail is unnecessary because an output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding cross-parameter constraints the schema documents only in isolation (nameContains requires locationCategoryId and can be rescued by datasetId/datacategoryId, sortField=name is the paging strategy for oversized categories). It adds little on limit/offset/dates, but that is acceptable given the schema already covers them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Search for geographic locations by category') and immediately states the return value (location IDs used downstream). It explicitly distinguishes itself from noaa_climate_list_location_categories (value enumeration) and from noaa_climate_find_stations / noaa_climate_fetch_data (consumers of the IDs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use routing: omit locationCategoryId for all types, use locationCategoryId=ST for the small states set, use nameContains plus a category for name lookup, and add datasetId/datacategoryId to shrink oversized categories. It also names the explicit alternative for enumerating categories and states the downstream hand-off to find_stations and fetch_data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All noaa-climate-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.