Skip to main content
Glama
NWS Weather MCP Server

NWS Weather MCP Server

by ShriniTechie

šŸŒ¤ļø 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 FunctionDeclaration objects, 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_alerts

  • get_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-server

2. Install Dependencies

Initialize the environment and install the project dependencies using uv:

uv sync

3. 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.py

The client will:

  1. Start the MCP weather server.

  2. Establish communication with the server.

  3. Discover the available MCP tools.

  4. Convert MCP schemas into Gemini function declarations.

  5. Send the available tools to Gemini.

  6. Process the user's request.

  7. Execute the required weather tools.

  8. Retrieve live data from the NWS API.

  9. Return the tool results to Gemini.

  10. 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_key

Instead, 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 tools
get_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

    B3.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to access real-time US weather forecasts and alerts through the National Weather Service API.
      2
      ISC
    • F
      license
      B
      quality
      D
      maintenance
      Provides 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.
      2
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time weather alerts and forecasts from the National Weather Service for US locations, integrating with AI assistants via the Model Control Protocol.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides weather forecasts and alerts for US locations via the National Weather Service API, enabling AI assistants to deliver real-time weather information.
      28 npm
      ISC