Weather Forecast Server

A Model Context Protocol (MCP) server that enables LLMs to retrieve weather forecasts from Israeli websites using browser automation with Playwright. This project demonstrates how to build MCP tools that maintain state across sequential tool calls, allowing an LLM to control a browser interactively.

Project Overview

This project implements an MCP server using the official Anthropic MCP SDK in Python. It provides tools for:

• Opening a browser and navigating to an Israeli weather forecast website
• Entering city names into search fields
• Selecting cities from autocomplete dropdowns
• Extracting weather data from the loaded page

The key feature is the global state mechanism that persists browser and page instances across different tool calls, enabling sequential operations on the same browser page.

Architecture

Components

• host.py: Main chat host that manages MCP clients and orchestrates tool calls with Anthropic's Claude API
• weather_Israel.py: MCP server implementing browser automation tools for Israeli weather forecasts
• weather_USA.py: MCP server implementing API-based weather tools for USA weather data
• client.py: MCP client implementation for connecting to MCP servers via stdio transport

Global State Management

The weather_Israel.py module uses a BrowserState class to maintain global browser and page instances:

• playwright: The Playwright async context
• browser: The Chromium browser instance (headless=False for visibility)
• page: The browser page for navigation and interaction

This state persists across tool calls, allowing sequential operations like:

1. Open browser → 2. Enter city → 3. Select city → 4. Extract data

Prerequisites

• Python 3.13 or higher
• uv package manager
• Anthropic API key (set in .env file)

Installation

1. Clone the repository and navigate to the project directory:

cd project-template

2. Install dependencies using uv:

uv sync

3. Install Playwright Chromium browser:

uv run playwright install chromium

4. Set up your environment variables:

# Edit .env and add your ANTHROPIC_API_KEY

Usage

Running the MCP Server

Start the interactive chat host:

uv run host.py

This will:

• Connect to the configured MCP servers (weather_Israel.py and weather_USA.py)
• Start an interactive chat loop
• Allow you to ask questions that trigger tool calls

Example Questions

Once the host is running, you can ask questions like:

Israeli Weather:

• "What is the weather in Jerusalem today?"
• "Tell me the forecast for Tel Aviv"
• "What's the current temperature in Haifa?"

USA Weather:

• "Are there any weather alerts for California?"
• "What's the forecast for New York City?"
• "Get the weather forecast for latitude 37.7749, longitude -122.4194"

How It Works

When you ask a question, the system:

1. Sends your query to Claude via the Anthropic API
2. Claude determines which tools to call based on your question
3. The host executes the tools in sequence (e.g., open browser → enter city → select → extract)
4. Results are returned to Claude for final response generation
5. The answer is displayed in the chat

MCP Tools

weather_Israel.py Tools

open_weather_forecast_israel()

Launches a Chromium browser (headless=False) and navigates to https://www.weather2day.co.il/forecast.

enter_weather_forecast_city_israel(city: str)

Locates the search input field and types the given city name into it.

• Parameter: city - The name of the Israeli city (e.g., "Jerusalem", "Tel Aviv")

select_weather_forecast_city_israel()

Waits for the autocomplete dropdown to appear and clicks the first city in the list.

extract_weather_forecast_israel()

Extracts weather data from the loaded page, cleans up HTML and whitespace, and returns the text for LLM processing.

weather_USA.py Tools

get_alerts_in_USA(state: str)

Gets weather alerts for a USA state.

• Parameter: state - Two-letter USA state code (e.g., CA, NY)

get_forecast_in_USA(latitude: float, longitude: float)

Gets weather forecast for a location in USA.

• Parameters:
  • latitude - Latitude of the location
  • longitude - Longitude of the location

Development

Adding New MCP Servers

To add a new MCP server:

1. Create a new Python file (e.g., weather_Europe.py)
2. Import FastMCP and create an instance:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-Europe")

3. Define tools using the @mcp.tool() decorator:

@mcp.tool()
async def your_tool_name(param: str) -> str:
    """Tool description"""
    # Your implementation
    return result

4. Add the main entry point:

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

5. Register the server in host.py by adding it to the mcp_clients list:

self.mcp_clients: list[MCPClient] = [
    MCPClient("./weather_USA.py"),
    MCPClient("./weather_Israel.py"),
    MCPClient("./weather_Europe.py")  # Add your new server
]

Debugging

• The browser runs in headless mode by default. Set headless=False in BrowserState.ensure_browser() to see the browser actions.
• Check the console output for tool execution logs and error messages.
• Use the @mcp.tool() decorator's docstring to provide clear descriptions for the LLM.

Troubleshooting

Browser not launching: Ensure Playwright Chromium is installed with uv run playwright install chromium

Timeout errors: The website might be slow or loading differently. Adjust timeout values in the tool functions.

Selector not found: The website structure may have changed. Update the CSS selectors in the tool functions.

API errors: Verify your Anthropic API key is correctly set in the .env file.

License

This project is part of an academic project for learning MCP (Model Context Protocol) implementation.

Acknowledgments

• Built with Anthropic MCP SDK
• Powered by Anthropic Claude
• Browser automation powered by Playwright
• Dependency management with uv