# `nws__nws_get_forecast`

**Nws Get Forecast**

Get the weather forecast for a US location. Returns either named 12-hour periods (default) or hourly breakdowns.

- Server: [US National Weather Service](https://gateway.mcpharbor.dev/docs/servers/nws) (`dev.mcpharbor.gateway/nws`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/nws`
- Upstream tool: exposed by the provider; called through this gateway as `nws__nws_get_forecast`
- Provider terms: <https://www.weather.gov/disclaimer> (verified 2026-09-19)
- Upstream API documentation: <https://www.weather.gov/documentation/services-web-api>
- Rate limit: 300 requests per minute
- Attribution required: No attribution required. Must not claim the content as your own, imply NOAA/NWS endorsement, or modify content and present it as official government material. Third parties producing copyrighted works predominantly of NWS material must add a notice identifying the NWS material as not subject to copyright. A User-Agent identifying the app (ideally with contact info) is required on every request.

## Parameters

- `cursor` (string, optional): Opaque continuation token from a previous response's nextCursor, to retrieve the next 48 periods. Omit for the first page. Every call re-fetches the forecast, so consecutive periods are contiguous ...
- `hourly` (boolean, optional): If true, returns hourly forecast (48 one-hour periods per page, ~156 available) instead of 12-hour named periods (14 periods). Hourly includes dewpoint and relative humidity. Default: `false`.
- `latitude` (number, required): Latitude in decimal degrees (e.g., 47.6062).
- `longitude` (number, required): Longitude in decimal degrees (e.g., -122.3321).

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: nws__nws_get_forecast
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "latitude": 1,
      "longitude": 1
    },
    "name": "nws__nws_get_forecast"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> No attribution required. Must not claim the content as your own, imply NOAA/NWS endorsement, or modify content and present it as official government material. Third parties producing copyrighted wo...

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "readOnlyHint": true
  },
  "description": "Get the weather forecast for a US location. Returns either named 12-hour periods (default) or hourly breakdowns.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "cursor": {
        "description": "Opaque continuation token from a previous response's nextCursor, to retrieve the next 48 periods. Omit for the first page. Every call re-fetches the forecast, so consecutive periods are contiguous within one response; NWS reissues forecasts through the day, so a later call can window a regenerated period array.",
        "type": "string"
      },
      "hourly": {
        "default": false,
        "description": "If true, returns hourly forecast (48 one-hour periods per page, ~156 available) instead of 12-hour named periods (14 periods). Hourly includes dewpoint and relative humidity.",
        "type": "boolean"
      },
      "latitude": {
        "description": "Latitude in decimal degrees (e.g., 47.6062).",
        "maximum": 90,
        "minimum": -90,
        "type": "number"
      },
      "longitude": {
        "description": "Longitude in decimal degrees (e.g., -122.3321).",
        "maximum": 180,
        "minimum": -180,
        "type": "number"
      }
    },
    "required": [
      "latitude",
      "longitude"
    ],
    "type": "object"
  },
  "name": "nws__nws_get_forecast",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "location",
          "generatedAt",
          "periods",
          "totalCount",
          "shown",
          "mode"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "error": {
        "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: `out_of_scope`: Coordinates fall outside US National Weather Service coverage. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "out_of_scope"
                ],
                "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"
      },
      "generatedAt": {
        "description": "When the forecast was generated (ISO 8601)",
        "type": "string"
      },
      "location": {
        "additionalProperties": false,
        "description": "Resolved location metadata",
        "properties": {
          "city": {
            "description": "City name",
            "type": "string"
          },
          "county": {
            "description": "County zone code for chaining to nws_search_alerts",
            "type": "string"
          },
          "forecastZone": {
            "description": "Forecast zone code for chaining to nws_search_alerts",
            "type": "string"
          },
          "office": {
            "description": "NWS Weather Forecast Office code",
            "type": "string"
          },
          "state": {
            "description": "State name",
            "type": "string"
          },
          "timeZone": {
            "description": "IANA time zone",
            "type": "string"
          }
        },
        "required": [
          "city",
          "state",
          "office",
          "timeZone",
          "forecastZone",
          "county"
        ],
        "type": "object"
      },
      "mode": {
        "description": "Forecast mode: \"hourly\" or \"7-day\"",
        "type": "string"
      },
      "nextCursor": {
        "description": "Opaque token for the next page of periods — pass it back as `cursor`. Omitted when this is the last page.",
        "type": "string"
      },
      "notice": {
        "description": "Set when periods remain beyond this page, or when the supplied cursor points past the end of the period array.",
        "type": "string"
      },
      "periods": {
        "description": "Forecast periods",
        "items": {
          "additionalProperties": false,
          "description": "Single forecast period with time range, conditions, and narrative",
          "properties": {
            "detailedForecast": {
              "description": "Full narrative forecast",
              "type": "string"
            },
            "dewpointC": {
              "description": "Dewpoint in Celsius (hourly only)",
              "type": [
                "number",
                "null"
              ]
            },
            "endTime": {
              "description": "Period end (ISO 8601)",
              "type": "string"
            },
            "name": {
              "description": "Period name (e.g., \"Today\", \"Tonight\") or hour label",
              "type": "string"
            },
            "precipChancePct": {
              "description": "Probability of precipitation in percent (0-100)",
              "type": [
                "number",
                "null"
              ]
            },
            "relativeHumidityPct": {
              "description": "Relative humidity in percent (0-100, hourly only)",
              "type": [
                "number",
                "null"
              ]
            },
            "shortForecast": {
              "description": "Brief forecast (e.g., \"Mostly Sunny\")",
              "type": "string"
            },
            "startTime": {
              "description": "Period start (ISO 8601)",
              "type": "string"
            },
            "temperature": {
              "description": "Temperature value",
              "type": "number"
            },
            "temperatureUnit": {
              "description": "Temperature unit (F or C)",
              "type": "string"
            },
            "windDirection": {
              "description": "Wind direction (e.g., \"NW\")",
              "type": "string"
            },
            "windSpeed": {
              "description": "Wind speed (e.g., \"10 mph\")",
              "type": "string"
            }
          },
          "required": [
            "name",
            "startTime",
            "endTime",
            "temperature",
            "temperatureUnit",
            "windSpeed",
            "windDirection",
            "shortForecast",
            "detailedForecast",
            "precipChancePct",
            "dewpointC",
            "relativeHumidityPct"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "shown": {
        "description": "Number of forecast periods in this page (at most 48).",
        "type": "number"
      },
      "totalCount": {
        "description": "Total forecast periods available upstream before the page window was applied — NOT the number in this page, which is shown. Compare it against shown to tell whether periods were withheld.",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Nws Get Forecast"
}
```