Skip to main content
Glama
Yeudit-Grayover

MCP Weather Forecast Server

by Yeudit-Grayover
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

MCP 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.

Related MCP server: Weather Israel MCP Server

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

  1. Install dependencies using uv:

uv sync

  1. Install Playwright Chromium browser:

uv run playwright install chromium

  1. 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")

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

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

  1. Add the main entry point:

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

if __name__ == "__main__":
    main()

  1. 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

Available Tools

4 tools
enter_weather_forecast_city_israelA

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

Args: city: The name of the Israeli city to search for (e.g., "Jerusalem", "Tel Aviv")

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explicitly discloses the main behavior: locating a field and typing a city name. While it does not cover edge cases like pre-existing text or missing fields, the action is simple and non-destructive, making the description reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: one sentence for the action and an Args block for the parameter. No unnecessary information, and the key verb is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter UI entry tool, this description is complete. It explains the core action and parameter. An output schema exists, so return values are not required. The scope is narrow, and the description provides enough context for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines 'city' as a string. The description adds meaningful context by specifying it's an Israeli city and gives examples (Jerusalem, Tel Aviv). This clarifies the expected value and compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: it locates the search input field and types the given city name. This specific verb+resource phrasing distinguishes it from siblings like open_weather_forecast_israel, select_weather_forecast_city_israel, and extract_weather_forecast_israel, which imply different stages of the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when a city name needs to be entered into a weather forecast search. However, it does not explicitly state when to use this tool versus alternatives (e.g., select_weather_forecast_city_israel) or mention any prerequisites or exclusions. This leaves room for the agent to infer the correct context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extract_weather_forecast_israelA

Extracts the current weather and forecast information from the loaded page.

This tool scrapes the weather data from the page, cleans up excessive whitespaces and HTML, and returns the text for the LLM to use in answering user questions.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosure. It clearly states the tool scrapes data, cleans whitespaces and HTML, and returns text. This explains the transformation and output behavior, though it does not cover edge cases or error handling, which is acceptable for a read-only extraction tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundant information. The first sentence states the primary purpose, and the second explains the process and output. It is appropriately concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no annotations), the description fully explains what the tool does and what it returns. The existence of an output schema further reduces the need for detail, and the description is complete enough for an agent to understand when and how to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-related information because there are none to describe, and the schema is complete with no properties.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts current weather and forecast information from the loaded page, using the specific verb 'extracts' and identifying the resource. This distinguishes it from sibling tools that open, enter, or select data, as it focuses solely on extraction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used after a page is loaded ('from the loaded page') and indicates the output is intended for the LLM to answer questions. It does not explicitly mention alternatives or exclusions, but the context is clear and sufficient for the tool's role in the workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

open_weather_forecast_israelA

Launches a Chromium browser and navigates to the Israeli weather forecast website.

This tool opens the browser (headless=False for visibility) and loads the forecast page.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses headless=False to make browser visible, which is useful behavioral context beyond the schema. However, with no annotations, it does not describe what the tool returns, whether it waits for page load, or any other side effects besides opening the browser.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences clearly state the main action and an important implementation detail. No filler or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter tool, the description adequately captures the core behavior. It lacks any mention of how this tool fits into the larger workflow with sibling tools (e.g., as a prerequisite for extraction), but given the output schema exists and no return value needs explanation, the gap is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100% and no parameter description is needed. Baseline 4 applies because there is nothing extra to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it launches a Chromium browser and navigates to a specific weather forecast website. The action is distinct from sibling tools that handle entering, selecting, or extracting weather data, so it is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool relative to siblings. It does not mention that it should be the initial step before using enter/select/extract tools, nor does it provide any prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

select_weather_forecast_city_israelA

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

This tool should be called after entering a city name to select it from the dropdown.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses key behavioral traits: it waits for the dropdown to appear and clicks the first city. This is transparent about the operation and its asynchronous nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and every sentence contributes essential information. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a zero-parameter tool: it explains the purpose, timing, and expected behavior. It could mention the specific sibling tools by name, but the phrase 'after entering a city name' sufficiently hints at the workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description appropriately explains the context rather than parameter details. Per rubric, 0 params baseline is 4, and the description adds value by clarifying when to invoke it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: waiting for the autocomplete dropdown and clicking the first city. It specifies the resource (city selection) and the verb (click), making it distinct from siblings like enter_weather_forecast_city_israel.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'This tool should be called after entering a city name,' which provides clear when-to-use guidance. It does not name alternatives or exclusions, so it misses a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedenter_weather_forecast_city_israel
    • First observedextract_weather_forecast_israel
    • First observedopen_weather_forecast_israel
    • First observedselect_weather_forecast_city_israel
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool serves a distinct stage of a linear workflow: opening the site, entering a city, selecting from autocomplete, and extracting data. There is no overlap in purpose, and the descriptions clearly delineate when each should be used.

Naming Consistency5/5

All tool names follow the same verb_noun pattern (open_, enter_, select_, extract_) with a consistent 'weather_forecast_israel' suffix. This makes the sequence and intent of each tool predictable and uniform.

Tool Count5/5

Four tools is ideal for this focused browser automation workflow. Each tool maps to a necessary step in the process, with no redundant or missing steps for the stated purpose.

Completeness5/5

The tools cover the full lifecycle from opening the forecast page to extracting the desired weather data. There are no obvious gaps that would prevent an agent from successfully retrieving a forecast for any Israeli city.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers