Weather MCP: Model Context Protocol Example

This project demonstrates an implementation of the Model Context Protocol (MCP) for a weather information service. It shows how language models (LLMs) can interact with external tools through a standardized interface.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables language models to discover and use tools during a conversation. MCP provides:

• Standard interfaces for tools and LLMs to communicate
• Runtime discovery of available tools and their capabilities
• Consistent tooling across different models and platforms

Project Architecture

This project consists of two main components:

1. MCP Server (weather.py)

The server provides weather tools through the MCP protocol:

• Uses the FastMCP library to register and expose tools
• Communicates via stdin/stdout (stdio transport)
• Provides two main tools:
  • get_alerts: Retrieves weather alerts for a US state
  • get_forecast: Gets weather forecasts for a location by coordinates
• Fetches data from the National Weather Service (NWS) API

2. MCP Client (test_client.py)

The client coordinates between a language model (Claude) and the MCP server:

• Spawns the server process and establishes communication
• Queries available tools from the server
• Exposes these tools to Claude through the Anthropic API
• Executes tool calls requested by Claude
• Returns tool results back to Claude for continued processing

Client-Server Interaction Flow

The MCP architecture enables a seamless interaction between LLMs and tools:

1. Initialization:

   • Client spawns the server process
   • Client establishes a connection via stdio
   • Client calls initialize to start the MCP session
   • Client discovers available tools via list_tools

2. Tool Registration:

   • Server registers functions as tools using the @mcp.tool() decorator
   • Each tool has a name, description, and input schema
   • Tools are exposed through the MCP interface

3. User Interaction:

   • User submits a query to the client
   • Client forwards the query to Claude with available tools

4. Tool Execution Cycle:

   • Claude decides whether to use tools based on the query
   • If tools are needed, Claude returns a tool_use object
   • Client sends tool call to the server via MCP's call_tool
   • Server executes the tool and returns results
   • Client forwards tool results back to Claude
   • Claude incorporates tool results into its response

5. Response Generation:

   • Claude processes all tool results
   • Claude generates a final response for the user
   • Client displays the final response

Setup and Usage

Prerequisites

• Python 3.9+
• An Anthropic API key (for Claude)
• UV - Fast Python package installer and resolver

Installation

1. Clone this repository
2. Set up with UV:

   # Install dependencies using UV
   uv sync
   
   # Or if using pyproject.toml
   uv pip install -e .
   

3. Create a .env file with your Anthropic API key:

   ANTHROPIC_API_KEY=your_api_key_here
   

Running the Application

1. Start the client with the server script:

   uv run test_client.py mcp_server_weather.py
   

2. Type weather-related queries, such as:
   • "What's the weather forecast for San Francisco?"
   • "Are there any weather alerts in CA?"
   • "Will it rain tomorrow in Seattle? The coordinates are 47.6062, -122.3321"

Using the MCP Inspector

For debugging and testing your MCP server, you can use the MCP Inspector:

1. Run the inspector with your server script:

   npx @modelcontextprotocol/inspector python weather.py
   

2. This will open a web UI in your browser where you can:

   • View available tools and their schemas
   • Test tool calls directly without needing an LLM
   • Debug server behavior and responses

Technical Details

Server Implementation

The server uses the FastMCP class to register Python functions as tools:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    # Implementation...

Client Implementation

The client manages the tool execution cycle:

# Execute tool call through MCP
result = await self.session.call_tool(tool_name, tool_args)

# Add tool result to conversation history
messages.append({
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result.content
        }
    ]
})

Resources

• MCP Documentation
• Anthropic API Documentation
• National Weather Service API

License

MIT License