nws-php-mcp

A Model Context Protocol (MCP) server built with Laravel that exposes real-time weather data from the National Weather Service (NWS) API to AI assistants and MCP-compatible clients.

• 7-day and hourly weather forecasts for any US location
• Current conditions from the nearest NWS observation station
• Active weather alerts and warnings by coordinates or US state
• NWS forecast office and observation station lookup
• Supports both HTTP (Streamable HTTP) and stdio transports
• Built-in response caching to reduce NWS API load

• PHP 8.3+
• Composer
• Node.js & npm (for asset building)

git clone https://github.com/benjaminhansen/nws-php-mcp
cd nws-php-mcp
composer run setup

The setup script installs dependencies, copies .env.example to .env, generates an app key, runs migrations, and builds frontend assets.

Edit .env and set the NWS-specific variables:

| Variable | Description | Default | |---|---|---| | NWS_APP_DOMAIN | Your app's domain (sent as User-Agent to NWS API) | — | | NWS_APP_CONTACT | Contact email (sent as User-Agent to NWS API) | — | | NWS_TIMEZONE | Timezone for date/time formatting | UTC | | NWS_CACHE_ENABLED | Enable response caching | true | | NWS_CACHE_LIFETIME | Cache TTL in seconds | 3600 |

> Note: The NWS API requires a descriptive User-Agent header containing a domain and contact address. Set NWS_APP_DOMAIN and NWS_APP_CONTACT to avoid request rejections.

Start the Laravel dev server:

composer run dev

The MCP endpoint will be available at:

POST http://localhost:8000/mcp

Point your MCP client at this URL.

Run the artisan command directly:

php artisan mcp:start nws

A