天气数据服务器

🌤️ MCP-сервер для погоды

MCP-сервер для получения данных о погоде через Open-Meteo API. Предоставляет инструменты для получения текущей погоды, прогноза и поиска местоположений.

Преимущества Open-Meteo:

• ✅ Бесплатный и открытый API
• ✅ Не требует регистрации и API ключа
• ✅ Высокая точность прогнозов
• ✅ Обновления каждый час
• ✅ Поддержка 80+ лет исторических данных

📋 Требования

• Python 3.10+ (обязательно, MCP SDK требует Python 3.10 или выше)
  • Если у вас более старая версия, см. SETUP.md для инструкций по обновлению
• API ключ не требуется! Open-Meteo полностью бесплатный

🚀 Установка

1. Клонируйте репозиторий или создайте проект:

   复制

   cd MCPWeather
   

2. Создайте виртуальное окружение:

   复制

   # Убедитесь, что используете Python 3.10+
   python3 --version  # Должно быть 3.10 или выше
   
   python3 -m venv venv
   # Если python3 указывает на старую версию, используйте конкретную:
   # python3.10 -m venv venv
   # или
   # python3.11 -m venv venv
   

3. Активируйте виртуальное окружение:

   复制

   # На macOS/Linux:
   source venv/bin/activate
   
   # На Windows:
   venv\Scripts\activate
   

4. Установите зависимости:

   复制

   pip install -r requirements.txt
   

5. Создайте файл .env на основе .env.example (опционально):

   复制

   cp .env.example .env
   

   Примечание: Open-Meteo не требует API ключа, поэтому файл .env необязателен. Вы можете использовать настройки по умолчанию.

⚙️ Конфигурация для Cursor и AI-агентов

Сервер уже настроен в .cursor/mcp.json для использования Python из виртуального окружения. Убедитесь, что:

1. Виртуальное окружение создано (venv папка существует)
2. Зависимости установлены в виртуальное окружение
3. Cursor перезапущен после добавления конфигурации
4. MCP-сервер активирован в настройках Cursor

Примечание: API ключ не требуется, так как Open-Meteo полностью бесплатный!

Подключение к Claude Desktop, глобальному Cursor и другим MCP-клиентам описано в AGENT_SETUP.md.

Развертывание на удаленном сервере (Docker, systemd, Nginx) описано в DEPLOYMENT.md.

🛠️ Использование

Инструменты (Tools)

1. get_current_weather

Получение текущей погоды для указанного местоположения.

Параметры:

• location (опционально, string) - Название города или координаты в формате "lat,lon"
• lat (опционально, number) - Широта
• lon (опционально, number) - Долгота

Пример:

@weather get_current_weather location="Санкт-Петербург"

или

@weather get_current_weather lat=55.75396 lon=37.620393

2. get_weather_forecast

Получение прогноза погоды на несколько дней.

Параметры:

• days (опционально, integer, по умолчанию 3) - Количество дней прогноза (1-7)
• location (опционально, string) - Название города или координаты
• lat (опционально, number) - Широта
• lon (опционально, number) - Долгота

Пример:

@weather get_weather_forecast days=5 location="Новосибирск"

3. search_location

Поиск координат по названию города.

Параметры:

• city_name (обязательно, string) - Название города

Пример:

@weather search_location city_name="Москва"

Промпты (Prompts)

1. current_weather

Быстрое получение текущей погоды.

Пример:

@weather current_weather location="Москва"

2. weather_forecast

Получение прогноза погоды.

Пример:

@weather weather_forecast location="Санкт-Петербург" days=3

3. weather_summary

Сводка погоды с рекомендациями (что надеть, стоит ли брать зонт).

Пример:

@weather weather_summary location="Москва"

📊 Формат вывода

Текущая погода:

🌤️ Погода в Москве
━━━━━━━━━━━━━━━━━━━━━━━
🌡️  Температура: 15°C (ощущается как 13°C)
☁️  Условия: облачно с прояснениями
💧 Влажность: 65%
📊 Давление: 750 мм рт.ст.
💨 Ветер: 5.2 м/с, юго-западный
🕐 Обновлено: 14:30

💡 Рекомендация: Возьмите лёгкую куртку

Прогноз погоды:

📅 Прогноз погоды в Москве на 3 дней
━━━━━━━━━━━━━━━━━━━━━━━

☀️ 27.01.2026 (Пн)
   🌡️  10°C / 15°C
   ☁️  ясно
   💧 Влажность: 60%

⛅ 28.01.2026 (Вт)
   🌡️  8°C / 12°C
   ☁️  облачно с прояснениями
   🌧️  Осадки: 2.5 мм
   💧 Влажность: 75%

🔧 Настройки

Все настройки можно изменить в файле .env:

• YANDEX_API_KEY - API ключ Яндекс Погоды (обязательно)
• DEFAULT_LANG - Язык ответа API (по умолчанию ru_RU)
• DEFAULT_LOCATION - Местоположение по умолчанию
• CACHE_TTL - Время жизни кэша в секундах (по умолчанию 600)
• LOG_LEVEL - Уровень логирования (DEBUG, INFO, WARNING, ERROR)
• REQUEST_TIMEOUT - Таймаут запросов к API в секундах

💾 Кэширование

Сервер использует in-memory кэш для уменьшения количества запросов к API:

• Кэш хранится в памяти процесса
• Время жизни записей: 10 минут (настраивается через CACHE_TTL)
• Кэш автоматически очищается от устаревших записей

🏗️ Архитектура проекта

weather-mcp-server/
├── server.py                 # Основной файл MCP-сервера
├── config.py                # Настройки и конфигурация
├── weather/
│   ├── __init__.py
│   ├── provider.py          # Провайдер Open-Meteo API
│   ├── formatter.py         # Форматирование данных
│   └── cache.py             # Кэширование запросов
├── requirements.txt
├── .env.example
├── .cursor/
│   └── mcp.json             # Конфигурация для Cursor
└── README.md

Ошибка «Сервер недоступен» (порт 8000 и MCP на 9001)

Если в приложении с «Чатом о погоде» появляется сообщение «Сервер недоступен», для работы чата должен быть доступен MCP на порту 9001.

Вариант 1: Свой MCP-Weather на порту 9001

В каталоге проекта выполните:

python3 server_remote.py --host 0.0.0.0 --port 9001

Вариант 2: Указать URL уже запущенного MCP-сервера

Если MCP-сервер уже слушает на 9001 (на этой машине или удалённо), в .env укажите:

MCP_WEATHER_SERVER_URL=http://127.0.0.1:9001

Убедитесь, что сервер действительно слушает порт 9001.

Проверка доступности

• API dev-сервера (порт 8000):

  复制

  curl http://localhost:8000/api/health
  

• MCP-сервер погоды (порт 9001):

  复制

  curl http://localhost:9001/health
  

• Скрипт проверки (API + MCP):

  复制

  python3 check_server.py
  

После создания .env (с при необходимости MCP_WEATHER_SERVER_URL) и запуска npm run dev сообщение «Сервер недоступен» должно пропасть, если вы заходите на тот же хост, где запущен dev-сервер.

🐛 Обработка ошибок

Сервер обрабатывает следующие ошибки:

• 400 - Неверные параметры запроса
• 429 - Превышен лимит запросов (10,000 в день для бесплатного использования)
• 500+ - Ошибка сервера Open-Meteo
• Ошибки сети и таймауты

Все ошибки логируются и возвращаются в понятном формате.

📝 Логирование

Логи записываются в консоль с указанием уровня важности:

• DEBUG - Детальная информация для отладки
• INFO - Общая информация о работе
• WARNING - Предупреждения
• ERROR - Ошибки

Уровень логирования настраивается через переменную LOG_LEVEL в .env.

🔗 Полезные ссылки

• Open-Meteo Weather API - бесплатный и открытый API для погоды
• Open-Meteo GitHub - исходный код API
• MCP Protocol
• MCP Python SDK

📄 Лицензия

Этот проект создан для использования с Cursor IDE и MCP Protocol.

🤝 Поддержка

Если у вас возникли проблемы:

1. Проверьте, что все зависимости установлены
2. Проверьте логи на наличие ошибок
3. Убедитесь, что интернет-соединение активно
4. Убедитесь, что используете Python 3.10+
5. Проверьте, что виртуальное окружение активировано

Приятного использования! 🌤️