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

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum number of results to return (1–1000). Defaults to 25.
`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

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when no locations matched — echoes applied filters and suggests how to broaden.
`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.

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.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, so safety is covered structurally, but the description adds genuinely non-obvious behavior: the CDO API exposes no name parameter, so this server enumerates the category and performs substring matching itself; the 4000-location bound on that behavior; and the fact that datasetId/datacategoryId can shrink an oversized category back under the limit. This mechanical disclosure goes well beyond what the annotations convey. No contradiction with annotations.

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?

The description is long, running as a single dense paragraph, but every sentence earns its place — purpose, category enumeration, naming workaround, size limits, pagination fallback, ID formats, downstream routing. Information density is high and the purpose is front-loaded before implementation details. It could be tightened into structured bullets, which costs it one point, but there is no filler.

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 lookup tool with output schema and openWorldHint, the description covers everything needed to call it correctly: the search mechanism, the nameContains workaround and its bound, category sizes, sort/pagination fallback for oversized categories, and explicit routing of results to downstream tools. Potential failure modes (oversized categories) are anticipated with concrete mitigations. Nothing an agent needs is missing.

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

Parameters5/5

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

Though schema coverage is 100% (baseline 3), the description adds substantial meaning the schema lacks: worked location-ID formats (FIPS:37 for NC, CITY:US530018 for Seattle, ZIP:98101, FIPS:US), the enumeration/size-limit mechanics behind nameContains, and concrete category semantics (ST=51 entries, CITY=thousands, ZIP). These worked examples and behavioral notes materially improve the agent's ability to construct correct parameter values.

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?

The description opens with a specific verb+resource combination — 'Search for geographic locations by category' — and immediately states the tool's actual purpose: returning location IDs that feed into station search and data queries. It distinguishes itself from siblings by name (noaa_climate_find_stations, noaa_climate_fetch_data) and by its role as the upstream ID lookup step. No ambiguity remains about what this tool does or how it fits the workflow.

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?

Provides explicit, actionable guidance: use locationCategoryId=ST to list US states (with the 51-entry size note), pass nameContains alongside locationCategoryId to find by name, and route to noaa_climate_list_location_categories when the category is unknown. It even gives a fallback strategy ('sort alphabetically with sortField=name and page through results') for oversized categories. Usage conditions and alternatives are named directly rather than left to inference.

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.