MCP Weather Agent
🌤️ MCP Weather Agent
Интеллектуальный многозонный погодный ассистент на базе OpenAI и Model Context Protocol (MCP).
Получайте прогнозы погоды и оповещения в реальном времени для Израиля и США через интерфейс чата на естественном языке. Агент интеллектуально направляет вопросы к соответствующему источнику данных и формирует ответы на основе живых веб-данных и официальных погодных API.
✨ Возможности
🤖 Чат на основе ИИ: Погодные запросы в диалоговом режиме с использованием GPT-4o-mini
🌍 Два источника данных:
🇮🇱 Израиль: Живой веб-скрапинг с Weather2day через Playwright
🇺🇸 США: Официальный API Национальной метеорологической службы
🔄 Умная маршрутизация инструментов: Агент автоматически выбирает нужный инструмент на основе вашего вопроса
💬 Естественный язык: Задавайте вопросы на простом английском; агент понимает контекст и намерение
🔐 Безопасность: Ключи API хранятся в
.envи исключены из системы контроля версий🎯 Интерактивность: Цикл чата в реальном времени с видимой автоматизацией браузера для запросов по Израилю
Related MCP server: MCP Weather Assistant
📋 Содержание
🚀 Быстрый старт
Запустите за 3 минуты:
# 1. Install dependencies
uv sync
uv run playwright install chromium
# 2. Create .env file with your OpenAI API key
copy .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-...
# 3. Run the agent
uv run .\host.py
# 4. Ask a weather question!
# Example: "What is the weather forecast for Jerusalem?"📦 Требования
Компонент | Версия | Назначение |
Python | 3.13+ | Среда выполнения |
OpenAI API Key | — | Доступ к модели GPT-4o-mini |
uv | Latest | Быстрый менеджер пакетов Python |
Chromium | Latest | Автоматизация браузера (Playwright) |
Интернет | — | Доступ к API и веб-скрапинг |
🔧 Настройка
1. Установка зависимостей
Откройте терминал в каталоге проекта и выполните:
# Install Python dependencies
uv sync
# Download Chromium browser for Playwright (required for Israel weather)
uv run playwright install chromiumПервый запуск занимает время? Да — Playwright загружает Chromium (~300 МБ). Это разовая операция.
2. Настройка ключа OpenAI API
Создайте файл .env в корне проекта:
# Option A: Copy the template
copy .env.example .env
# Option B: Create manually
echo OPENAI_API_KEY=your_openai_api_key > .envЗамените your_openai_api_key на ваш реальный ключ OpenAI API с platform.openai.com/account/api-keys.
⚠️ Важно: Никогда не коммитьте .env и не делитесь вашим ключом API. .gitignore уже исключает его.
3. Проверка установки
Проверьте настройку:
uv run .\host.pyВы должны увидеть:
Connected to server with tools: [...]
MCP Client Started!
Type your queries or 'quit' to exit.
Query:Нажмите Ctrl+C или введите quit для выхода.
▶️ Запуск агента
Запустите интерактивный чат:
uv run .\host.pyАгент запускается в интерактивном режиме. Введите вопрос о погоде и нажмите Enter. Агент:
✅ Анализирует ваш вопрос
🔍 Направляет к соответствующему погодному инструменту (Израиль или США)
🌐 Получает данные в реальном времени (для Израиля может открыться окно браузера)
📊 Обрабатывает и форматирует ответ
💬 Возвращает ответ
Введите quit для выхода.
Для запросов по Израилю: Автоматически открывается окно браузера Chromium. Это нормально — агент использует Playwright для взаимодействия с Weather2day. Окно закрывается после завершения запроса.
🏗️ Архитектура
┌─────────────────────────────────────────────────────────────────┐
│ OpenAI (GPT-4o-mini) │
│ (Tool Selection & Reasoning) │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌───────▼────────┐
│ MCP Host │ │ MCP Host │
│ (client.py) │ │ (client.py) │
└───────┬────────┘ └───────┬────────┘
│ │
┌───────▼──────────────┐ ┌──────▼─────────────┐
│ weather_Israel.py │ │ weather_USA.py │
│ (Playwright + Web) │ │ (NWS API) │
└───────┬──────────────┘ └──────┬─────────────┘
│ │
┌───────▼──────────────┐ ┌──────▼─────────────┐
│ Weather2day.co.il │ │ api.weather.gov│
│ (Live Web Browser) │ │ (REST API) │
└──────────────────────┘ └───────────────────┘Поток данных:
Вы задаёте вопрос в чате
Хост отправляет его в OpenAI с доступными инструментами
OpenAI выбирает, какой инструмент вызвать, на основе вопроса
Соответствующий MCP-сервер выполняет и возвращает данные
Хост форматирует и возвращает ответ
💬 Примеры запросов
🇮🇱 Погода в Израиле
What is the weather forecast for Jerusalem?
Give me the forecast for Tel Aviv.
What is the weather like in Haifa today?
Show me the forecast for Eilat.
What is the weather in Beer Sheva?
Is it going to rain in Kfar Saba tomorrow?
Tell me about the weather in Nazareth.
What's the forecast for Tiberias?Поддерживаемые города: Иерусалим, Тель-Авив, Хайфа, Эйлат, Беэр-Шева, Кфар-Сава, Тверия, Назарет и большинство крупных израильских городов, распознаваемых Weather2day.
🇺🇸 Погода в США
What is the weather forecast for New York City? (40.7128, -74.0060)
What's the weather at latitude 34.0522, longitude -118.2437? (Los Angeles)
Are there any active weather alerts in California?
What weather alerts are in effect in New York?
Give me the forecast for Chicago coordinates. (41.8781, -87.6298)
Are there any severe weather warnings in Texas?Формат:
Прогнозы: Используйте координаты широты/долготы
Оповещения: Используйте двухбуквенные коды штатов (
CA,NY,TXи т.д.)
🎯 Умное поведение агента
Агент понимает контекст:
✅ «Какая погода в Иерусалиме?» → Использует израильский инструмент
✅ «Я собираюсь в Нью-Йорк, какой прогноз?» → Использует инструмент США (40.71, -74.01)
✅ «Расскажи о погоде в Тель-Авиве и Лос-Анджелесе» → Вызывает оба инструмента
✅ «Сейчас идёт дождь в Чикаго?» → Направляет к инструменту США
📂 Структура проекта
MCP Weather/
├── host.py # Main chat host (OpenAI + tool orchestration)
├── client.py # MCP client connector
├── weather_Israel.py # Israel MCP server (Playwright + Web)
├── weather_USA.py # USA MCP server (NWS API)
├── pyproject.toml # Dependencies and project metadata
├── uv.lock # Locked dependency versions
├── .env.example # Template for environment variables
├── .env # Your API keys (git-ignored)
├── README.md # This file
└── .gitignore # Git exclusion rules🐛 Устранение неполадок
❌ OPENAI_API_KEY is missing
Проблема: Агент не может найти ваш ключ API.
Решение:
Убедитесь, что
.envсуществует в корне проекта (та же папка, что иhost.py)Проверьте, что файл содержит:
OPENAI_API_KEY=sk-your-actual-key-hereПерезапустите хост:
uv run .\host.py
❌ Браузер Chromium не запускается
Проблема: Ошибка «Failed to launch browser».
Решение:
uv run playwright install chromiumЕсли проблема сохраняется, проверьте место на диске (Chromium требуется ~500 МБ).
❌ Тайм-аут соединения или ошибки API
Проблема: «net::ERR_CONNECTION_RESET» или сбои запросов.
Решение:
Проверьте интернет-соединение
Убедитесь, что ваш ключ OpenAI API действителен на platform.openai.com
Проверьте использование API и биллинг
❌ Браузер для Израиля открывается, но поиск не работает
Проблема: Поиск города не возвращает подсказки.
Пояснение: Автодополнение Weather2day работает только на странице /forecast. Инструмент автоматически возвращается на эту страницу перед каждым поиском, но если это не удаётся:
Решение:
Убедитесь, что Chromium обновлён:
uv run playwright install --with-deps chromiumУбедитесь, что у вас есть доступ к
weather2day.co.ilПроверьте всплывающие окна или баннеры cookie (агент обрабатывает их, но при очень медленном соединении может произойти тайм-аут)
❌ «A server fails to connect»
Проблема: Ошибка соединения с MCP-сервером.
Решение:
# Run from the project directory
Set-Location .\project-template
uv run .\host.py❓ FAQ
В: Как агент решает, какой инструмент использовать?
О: GPT-4o-mini от OpenAI читает ваш вопрос и выбирает лучший инструмент на основе контекста (упомянутая страна/регион, предоставленные координаты и т.д.). Это не основано на правилах — используется понимание языка.
В: Могу ли я спросить о нескольких регионах в одном запросе?
О: Да! Агент может вызывать несколько инструментов. Попробуйте: «Какая погода в Тель-Авиве и Нью-Йорке?»
В: Почему браузер для Израиля открывается видимо?
О: Playwright автоматизирует Weather2day, вводя текст в живой поиск, выбирая результаты и читая страницу. Безголовый режим (невидимый) не работает с автодополнением этого сайта, основанным на JavaScript, поэтому браузер запускается видимо.
В: Сколько это стоит?
О: Вы платите OpenAI за вызовы API. Каждый запрос стоит ~$0.001–$0.01 в зависимости от длины ответа. Веб-скрапинг для Израиля бесплатен; API США бесплатен (NWS является публичным).
В: Что если я хочу добавить больше регионов?
О: Создайте новый MCP-сервер (например, weather_Europe.py) и зарегистрируйте его в host.py в self.mcp_clients. Смотрите существующие серверы для примера.
В: Безопасен ли мой ключ API?
О: Да. Ваш .env исключён из Git и хранится только локально. Никогда не вставляйте ключ в код или публичный чат.
В: Можно ли использовать это в производстве?
О: Это демонстрационный проект. Для производства:
Используйте асинхронную очередь запросов
Добавьте логирование и восстановление после ошибок
Кэшируйте прогнозы (погода меняется каждый час, а не каждый запрос)
Настройте мониторинг и оповещения
Используйте конфигурацию на основе переменных окружения
🔒 Безопасность
⚠️ Делать | ❌ Не делать |
✅ Держите | ❌ Коммитьте |
✅ Регулярно меняйте ключи API | ❌ Делитесь вашим ключом API |
✅ Используйте переменные окружения в проде | ❌ Хардкодьте секреты в коде |
✅ Проверяйте лимиты биллинга API | ❌ Оставляйте квоту без ограничений |
✅ Используйте HTTPS для вызовов API | ❌ Используйте HTTP в проде |
Если ваш ключ API раскрыт:
Немедленно отзовите его в OpenAI Dashboard
Сгенерируйте новый ключ
Обновите
.env
📝 Лицензия
Этот проект предоставляется как есть для образовательных целей. Подробности см. в LICENSE.
🤝 Вклад
Есть идеи по улучшению агента? Вклад приветствуется!
Форкните репозиторий
Создайте ветку для функции (
git checkout -b feature/amazing-feature)Закоммитьте изменения (
git commit -m 'Add amazing feature')Запушьте ветку (
git push origin feature/amazing-feature)Откройте Pull Request
📞 Поддержка
🐛 Сообщайте об ошибках через GitHub Issues
💡 Предлагайте функции в Discussions
📧 По вопросам безопасности пишите на email (не открывайте публичный issue)
Хороших прогнозов! 🌦️☀️
Available Tools
4 toolsenter_weather_forecast_city_israelC
מקבל שם עיר ומזין אותו בשדה החיפוש באתר מזג האוויר.
:param city_name: שם העיר בחיפוש (למשל: 'ירושלים', 'תל אביב')
| Name | Required | Description | Default |
|---|---|---|---|
| city_name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses only that it fills a search field; it does not say whether the search is submitted, what happens if the city is not found, whether the site must already be open, or what state the page is left in for the next sibling call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short lines with the action stated first and the parameter documented in a conventional :param block; nothing is padded. It is efficient, though the colon-prefixed param line is stylistically thin for a tool with a workflow dependency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. However, for a browser-automation step in a four-tool sequence, the description omits the ordering/state assumptions an agent needs, leaving a real gap despite the adequate parameter hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter, so the description must compensate, and it partially does by explaining that city_name is the search string and giving examples ('ירושלים', 'תל אביב'). It adds useful illustrative meaning but no format or validation constraints beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb and resource: it receives a city name and types it into the search field of the weather site. That is specific enough to distinguish a UI-entry step, though it never names or contrasts the sibling tools (select_weather_forecast_city_israel, open_weather_forecast_israel), so an agent must infer the ordering itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no mention of the sibling steps that presumably follow. The workflow role (enter search text, then select the city, then read content) is only implied by the tool names, not stated in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_weather_forecast_content_israelA
מחלקץ את הטקסט הגלוי מתוך דף התחזית הנוכחי שנפתח בדפדפן, מנקה רווחים מיותרים ומחזיר את התוכן ל-LLM לצורך מתן תשובה.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the extraction behavior and whitespace cleanup, which is useful, but omits what happens when no page is open, failure/error behavior, and any permission considerations. Adequate but incomplete for a zero-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence stating the action, with no wasted preamble. The trailing clause about returning content 'to the LLM to provide an answer' is mildly redundant but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and there are no parameters to document. The main remaining gap is state-dependence (what it requires the browser to already be showing), which is only implied rather than guaranteed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so the baseline of 4 applies. Nothing about parameters needs explaining and the description does not confuse the matter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: it extracts the visible text from the current forecast page open in the browser and returns a cleaned version. That is clear and distinguishable from open/enter/select siblings in the pipeline, though it never explicitly names how it differs from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: it works on the page 'opened in the browser', so the agent can infer it must run after opening and selecting a city. There is no explicit statement of prerequisites, exclusions, or what to do instead if the page is not ready.
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
פותח את דפדפן האינטרנט ומנווט לדף הבית של אתר מזג האוויר הישראלי.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the side effect that a browser window is opened, which is meaningful for an agent. It does not mention state (new tab vs. existing), auth, or what the user sees next, leaving gaps for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the action and destination are stated immediately. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (0 params, output schema present so return values need no explanation) and the description adequately covers the action. The remaining gap is routing context against the sibling tools, which is a moderate omission rather than a fatal one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies since no parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a concrete verb+resource in Hebrew: it opens the browser and navigates to the Israeli weather site's homepage. An agent can tell what the tool does. However, it never distinguishes itself from the three sibling tools (enter/select/get_weather_forecast_*), so it stops at 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of navigating to the 'homepage' implies this is the entry/starting step before the city-selection and content siblings, but there is no explicit statement of when to use it versus enter_weather_forecast_city_israel or get_weather_forecast_content_israel. Usage is only inferred.
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
בוחר את התוצאה הראשונה ברשימת הערים שנפתחה בעקבות החיפוש.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It usefully reveals that selection is deterministic ('first result'), meaning the agent cannot choose a specific city, but it omits what happens if the list is empty, whether it navigates to a new page, and any auth or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tight sentence with no padding, and the key constraint ('first result') is placed prominently. Appropriate length for a zero-argument UI step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, and there are no parameters. What remains unstated is the workflow contract (what must precede this call, what state follows it), which matters for a sequential UI-automation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless tool is 4, and the description adds no misleading parameter claims.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (selects) and a specific target (the first result in the city list opened by the search), which distinguishes it from siblings like enter_weather_forecast_city_israel or open_weather_forecast_israel. It stops short of explicitly naming the alternative tools, but the action and target are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'the city list that was opened following the search' implies this step follows a search and a list-opening step, giving sequencing context. However, it never states when to use this versus entering a city directly, nor any preconditions or failure conditions.
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.
4 tool updates
v0.1.0- First observed
enter_weather_forecast_city_israel - First observed
get_weather_forecast_content_israel - First observed
open_weather_forecast_israel - First observed
select_weather_forecast_city_israel
TDQS
Scored across 4 tools
Each tool maps to a distinct browser-automation step (open site, enter city, select result, extract content), so they are separable in principle. However, they form a rigid ordered pipeline with no way to tell from the names alone that they must be chained, and enter vs. select could be momentarily confused by a hurried agent.
All names are snake_case and share a predictable verb_..._israel suffix (open/enter/select/get_weather_forecast_..._israel). Minor structural deviation: open_weather_forecast_israel omits the 'city' segment the other three include, but the pattern is still readable and consistent.
Four tools is a reasonable count for this narrow scraping workflow. It is slightly granular, since a single 'fetch forecast for city' operation is split into four browser steps, but each step is individually actionable and the set stays well-scoped.
The surface covers the happy path open -> search -> select -> extract, but has no tool to close/reset the browser session, no error or no-result handling, and despite the generic server name 'MCP Weather Agent' it only supports Israeli locations. Agents can complete the core task but will hit dead ends on edge cases.
Maintenance
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.
Provide real-time and forecast weather information for locations in the United States using natura…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables users to query real-time weather data for Israeli cities using natural language, automatically scraping a weather website via Playwright and returning AI-generated answers.-
- FlicenseAqualityDmaintenanceEnables users to query weather information for Israel via Playwright browser automation and for the USA via a weather API, allowing an LLM to access real-time weather data and alerts.4-
- FlicenseNot gradedqualityCmaintenanceEnables natural language weather queries for Israeli cities with real-time data extracted via Playwright, plus USA weather alerts and forecasts via NWS API, all orchestrated by Groq LLM.1-
- FlicenseNot gradedqualityBmaintenanceEnables natural language weather queries for cities in Israel and the United States, combining browser automation and official API retrieval.-