NWS Weather MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NWS Weather MCP Server What's the forecast for Chicago?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
š¤ļø NWS Weather MCP Server & Agentic Client
A fully functional Model Context Protocol (MCP) server and custom LLM client that enables dynamic, real-time weather querying through the National Weather Service (NWS) API.
This project demonstrates an end-to-end AI agentic workflow using the ReAct pattern, where an LLM dynamically discovers available tools, determines the required parameters, executes tool calls through an MCP server, retrieves live weather data, and synthesizes the results into a natural-language response.
⨠Key Features
Model Context Protocol (MCP): Implements the MCP server/client architecture for tool discovery and standardized communication over
stdio.Dynamic Tool Discovery: The client discovers available MCP tools at runtime rather than relying on hardcoded tool definitions.
Zero-Shot Tool Calling: Dynamically translates MCP Pydantic schemas into Gemini
FunctionDeclarationobjects, allowing the LLM to understand and invoke available tools.National Weather Service Integration: Retrieves real-time weather alerts and forecast information from the NWS API.
Dynamic Coordinate Resolution: Weather information is retrieved based on dynamically determined geographic coordinates.
Decoupled Architecture: Separates the tool execution environment from the LLM reasoning engine.
Pydantic Validation: Uses Pydantic models to validate structured weather data returned by the MCP server.
Agentic Reasoning Loop: Demonstrates how an LLM can determine when additional contextual information or tool execution is required before generating a final response.
Related MCP server: Weather MCP Server
šļø Architecture
āāāāāāāāāāāāāāāāāāāāāāā
ā User ā
ā Natural Language ā
ā Request ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā Gemini Client ā
ā LLM Reasoning ā
ā / ReAct Loop ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
MCP Tool Discovery
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā MCP Client ā
ā Tool Schema Mapping ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
JSON-RPC / stdio
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā MCP Server ā
ā Weather Tools ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā NWS Weather API ā
ā Live Weather Data ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā Structured Weather ā
ā Data ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā Gemini ā
ā Response Synthesis ā
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāā
ā Natural Language ā
ā Response ā
āāāāāāāāāāāāāāāāāāāāāāāš§ How It Works
The application follows an agentic workflow where the LLM can dynamically discover and execute tools provided by the MCP server.
1. Tool Discovery
The Gemini client starts the weather MCP server and requests the tools exposed by the server.
Available tools include:
get_alertsget_forecast
The MCP client receives the tool definitions and their associated schemas.
2. Schema Translation
The MCP tool schemas are dynamically converted into Gemini-compatible FunctionDeclaration objects.
This allows Gemini to understand:
What tools are available
What each tool does
What parameters each tool expects
What information needs to be supplied for execution
3. Agentic Reasoning
The user provides a natural-language weather request.
Gemini analyzes the request and determines whether a tool needs to be called.
For example:
User:
What's the weather forecast for my location?
ā
Gemini determines:
I need geographic coordinates to retrieve the forecast.
ā
MCP Tool Call:
get_forecast(latitude, longitude)
ā
NWS API:
Returns forecast information.
ā
Gemini:
Synthesizes the weather data into a natural-language response.4. Tool Execution
The MCP server receives the requested tool call and executes the corresponding Python function.
The weather tool communicates with the National Weather Service API and retrieves the required information.
5. Data Validation
The returned data is validated using Pydantic models before being passed back to the client.
This provides a structured and predictable interface between the external API and the LLM.
6. Response Synthesis
Gemini receives the tool output and uses the retrieved information to generate a conversational response for the user.
š ļø Tech Stack
Technology | Purpose |
Python 3.11 | Application development |
MCP SDK | Model Context Protocol server/client implementation |
Gemini | LLM reasoning and tool calling |
google-genai | Gemini API integration |
httpx | HTTP communication with the NWS API |
Pydantic | Data validation and structured models |
asyncio | Asynchronous execution |
uv | Python package and environment management |
National Weather Service API | Live weather data |
š Project Structure
weather-mcp-server/
ā
āāā weather.py
ā āāā MCP weather server
ā
āāā client_gemini.py
ā āāā Gemini-powered MCP client and agentic reasoning loop
ā
āāā pyproject.toml
ā āāā Project configuration and dependencies
ā
āāā uv.lock
ā āāā Locked dependency versions
ā
āāā README.md
āāā Project documentationš Getting Started
Prerequisites
Make sure you have the following installed:
Python 3.11+
uv package manager
A valid Google Gemini API key
1. Clone the Repository
git clone https://github.com/ShriniTechie/weather-mcp-server.git
cd weather-mcp-server2. Install Dependencies
Initialize the environment and install the project dependencies using uv:
uv sync3. Configure the Gemini API Key
Set your Gemini API key as an environment variable.
Windows PowerShell
$env:GEMINI_API_KEY="your_actual_api_key_here"Linux / macOS
export GEMINI_API_KEY="your_actual_api_key_here"ā ļø Security: Never commit your API key to GitHub. Use environment variables or another secure secrets-management approach.
4. Run the Agentic Client
Start the integrated Gemini client:
uv run client_gemini.pyThe client will:
Start the MCP weather server.
Establish communication with the server.
Discover the available MCP tools.
Convert MCP schemas into Gemini function declarations.
Send the available tools to Gemini.
Process the user's request.
Execute the required weather tools.
Retrieve live data from the NWS API.
Return the tool results to Gemini.
Generate the final natural-language response.
š Agentic Execution Flow
User Request
ā
ā¼
Gemini LLM
ā
ā Determines required tool
ā¼
MCP Client
ā
ā Sends tool request
ā¼
MCP Server
ā
ā Executes Python function
ā¼
NWS API
ā
ā Returns weather data
ā¼
MCP Server
ā
ā Validates response
ā¼
MCP Client
ā
ā Returns tool result
ā¼
Gemini LLM
ā
ā Synthesizes response
ā¼
Final Answerš§ MCP Tools
get_alerts
Retrieves active weather alerts from the National Weather Service.
The tool can be used by the LLM when the user asks about active weather warnings or alerts.
get_forecast
Retrieves forecast information from the National Weather Service based on geographic coordinates.
The tool provides forecast information that can then be interpreted and summarized by Gemini.
š” Example Interaction
User:
What is the weather forecast for the requested location?
Agent:
I need to retrieve the forecast information.
MCP:
get_forecast(latitude=<latitude>, longitude=<longitude>)
NWS:
Returns structured forecast information.
Gemini:
The forecast is retrieved and synthesized into a
natural-language response for the user.The important aspect of this workflow is that the LLM is not simply generating an answer from its existing knowledge. It can discover and invoke external tools to retrieve live information before producing the final response.
šÆ Project Goals
This project was built to demonstrate practical concepts around:
Model Context Protocol (MCP)
LLM tool calling
Agentic AI workflows
ReAct-style reasoning
Dynamic tool discovery
Function calling
API integration
Structured data validation
Python asynchronous programming
Separation of reasoning and tool execution
LLM integration with external services
š Key Takeaways
This project demonstrates how an LLM application can be structured into separate components:
Reasoning Layer
Gemini is responsible for understanding the user's request, determining what information is required, and deciding which tools to invoke.
Tool Layer
The MCP server exposes weather-related capabilities through standardized tools.
Data Layer
The National Weather Service API provides live weather information.
Validation Layer
Pydantic provides structured validation of returned data.
This separation makes the architecture easier to understand, extend, and maintain.
š Security
Do not commit secrets or API keys to the repository.
For example, avoid committing:
GEMINI_API_KEY=your_actual_api_keyInstead, configure the API key through your environment.
You should also ensure sensitive configuration files are included in .gitignore.
Example:
.env
.venv/
__pycache__/
*.pycš Future Improvements
Potential extensions for this project include:
Adding additional weather-related MCP tools.
Supporting more external APIs.
Adding automated tests for MCP tools.
Improving error handling and retry logic.
Adding logging and observability.
Supporting multiple LLM providers.
Adding a web-based user interface.
Extending the agent with additional tool capabilities.
š References
Model Context Protocol (MCP) ā Protocol for connecting LLM applications with external tools and data sources.
National Weather Service API ā Provides weather forecasts and alerts.
Google Gemini API ā Provides LLM capabilities and function/tool calling.
uv ā Python package and environment management.
ā Why This Project?
The goal of this project is to demonstrate a practical implementation of an LLM-powered agent that can discover tools, reason about when to use them, execute external operations, and incorporate live API data into its responses.
It serves as a hands-on example of combining Python, MCP, LLM tool calling, APIs, structured data validation, and agentic workflows into a single application.
Available Tools
2 toolsget_alertsC
Get weather alerts for a US state.
Args:
state: Two-letter US state code (e.g. CA, NY)
Inputs: state (required). Returns: The output schema of get_alerts: an object containing a list.
get_forecastB
Get weather forecast for a location.
Args:
latitude: Latitude of the location
longitude: Longitude of the location
Inputs: latitude (required), longitude (required). Returns: The output schema of get_forecast: the object case, for contrast.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one retrieves weather alerts for a state, the other retrieves forecasts for coordinates. There is no overlap in functionality or parameters, making misselection unlikely.
Both tools follow the consistent get_verb_noun pattern: get_alerts and get_forecast. The naming is clean, predictable, and uses the same style throughout.
With only 2 tools, the server feels minimal for a weather domain. While the count is not extreme, it is on the thin side and likely covers only a fraction of what the NWS API offers.
The NWS provides a broad range of weather data including current conditions, radar, marine forecasts, and fire weather, but this server only covers alerts and forecasts. Significant functionality is missing, which will limit agent workflows.
Related MCP Connectors
US NWS weather alerts and 5-day forecasts for AI agents. $0.01 per call.
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
Current weather and forecast lookup as an agent tool.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to access real-time US weather forecasts and alerts through the National Weather Service API.2ISC
- FlicenseBqualityDmaintenanceProvides real-time US weather alerts and forecasts by integrating with the National Weather Service API. It enables AI assistants to fetch state-specific alerts and detailed local forecasts using geographic coordinates.21-
- FlicenseNot gradedqualityDmaintenanceProvides real-time weather alerts and forecasts from the National Weather Service for US locations, integrating with AI assistants via the Model Control Protocol.-
- AlicenseNot gradedqualityDmaintenanceProvides weather forecasts and alerts for US locations via the National Weather Service API, enabling AI assistants to deliver real-time weather information.28 npmISC