Yandex Weather MCP

Локальный MCP-сервер для получения данных из API Яндекс Погоды по координатам. Сервер прячет API-ключ от MCP-клиента, валидирует входные параметры, нормализует ответ API и кэширует запросы на 5-15 минут.

Технический консилиум

Backend-разработчик: на первом этапе нужны четыре инструмента MCP: текущая погода, прогноз, короткая сводка и сравнение двух точек. Запрашивать стоит координаты, язык, лимит дней, почасовой прогноз и расширенные поля. Пользователю полезны температура, ощущается как, состояние, ветер, влажность, давление, осадки, рассвет/закат и служебный признак кэша.

DevOps-инженер: локальный Docker-запуск должен получать секреты только через env, работать не от root и иметь простой healthcheck. Риски: stdio MCP плохо сочетается с обычной HTTP-проверкой, .env легко случайно закоммитить, а сеть из контейнера должна иметь доступ к API.

Специалист по API-интеграциям: клиенту нужен таймаут, понятная обработка 401/403/404/429/400, аккуратный JSON parsing и endpoint, который можно переопределить через env. Для первого этапа не стоит делать агрессивные retry: погодный запрос безопасен, но повтор при 429 только быстрее сожжет лимит.

Специалист по MCP: инструменты лучше возвращать JSON как text content, потому что это совместимо с большинством MCP-клиентов и удобно для отладки. Ошибки возвращаются структурированно в { error: { code, message, details } }.

Специалист по типизации и качеству: TypeScript + Zod дают строгие контракты на входе и нормализацию на выходе. В тестах нужно закрыть координаты, маппинг состояний, отсутствующий ключ, ошибки API, кэш и нормализацию.

Related MCP server: Open Weather13 MCP Server

Архитектурное решение

Для первого этапа выбран TypeScript / Node.js. Python быстрее для прототипа, Rust надежнее для production-бинарника, но TypeScript дает лучший баланс MCP-экосистемы, строгих типов, Docker-упаковки и скорости разработки.

Проект устроен так:

src/
  index.ts
  server.ts
  config.ts
  yandexWeatherClient.ts
  tools/
  schemas/
  utils/
Dockerfile
docker-compose.yml
README.md
.env.example

По документации: публично используемый endpoint Яндекс Погоды для прогноза обычно выглядит как https://api.weather.yandex.ru/v2/forecast с ключом в заголовке X-Yandex-API-Key. В коде endpoint вынесен в YANDEX_WEATHER_API_URL, чтобы без изменения сервера перейти на endpoint вашего тарифа, если в личном кабинете доступна другая версия.

Настройка

Получите API-ключ в кабинете Яндекс Погоды / Яндекс API, затем создайте .env:

cp .env.example .env

Заполните:

YANDEX_WEATHER_API_KEY=your_api_key_here
YANDEX_WEATHER_LANG=ru_RU
CACHE_TTL_SECONDS=600
LOG_LEVEL=info
MCP_TRANSPORT=http
HOST=0.0.0.0
PORT=3000

Не храните настоящий ключ в коде, Dockerfile или README.

Локальный запуск

npm install
npm run build
npm start

Для разработки:

npm run dev

Docker

Для серверного запуска используется HTTP transport MCP на /mcp. Создайте .env перед запуском:

cp .env.example .env

Заполните YANDEX_WEATHER_API_KEY, затем запустите:

docker compose up --build

Проверка здоровья:

curl http://localhost:3000/health

MCP endpoint:

http://localhost:3000/mcp

Если нужен локальный stdio-режим для MCP-клиента, запускайте Node напрямую или переопределите MCP_TRANSPORT=stdio:

{
  "mcpServers": {
    "yandex-weather": {
      "command": "npm",
      "args": ["start"],
      "env": {
        "YANDEX_WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

MCP tools

get_current_weather

Вход:

{
  "lat": 55.7558,
  "lon": 37.6173,
  "lang": "ru_RU"
}

Возвращает location, current и meta.

get_weather_forecast

Вход:

{
  "lat": 55.7558,
  "lon": 37.6173,
  "lang": "ru_RU",
  "days": 3
}

Возвращает прогноз по дням, частям суток и почасовым данным, если они доступны для тарифа/API.

get_weather_summary

Вход:

{
  "lat": 55.7558,
  "lon": 37.6173
}

Пример ответа:

{
  "summary": "Сейчас +18°C, ощущается как +16°C. Пасмурно, ветер 4 м/с, влажность 78%.",
  "advice": "Вероятность осадков повышенная, стоит взять зонт или дождевик."
}

compare_weather

Вход:

{
  "first": { "lat": 55.7558, "lon": 37.6173, "name": "Москва" },
  "second": { "lat": 59.9386, "lon": 30.3141, "name": "Санкт-Петербург" },
  "lang": "ru_RU"
}

Возвращает две нормализованные погодные карточки и сравнение по температуре, ветру и влажности.

Деплой на VDS

Требования

• Docker 24+ и Docker Compose V2 (docker compose)

• Открытый порт на сервере (например 3000) или Nginx как reverse proxy

Шаги

# 1. Клонировать репозиторий на сервер
git clone <url> yandex-weather-mcp
cd yandex-weather-mcp

# 2. Создать директорию для базы данных планировщика
mkdir -p data

# 3. Создать .env и вписать ключ
cp .env.example .env
nano .env   # выставить YANDEX_WEATHER_API_KEY и, если нужно, PORT

# 4. Запустить
docker compose up -d --build

# 5. Проверить
curl http://localhost:3000/health

После этого MCP endpoint доступен на http://<vds-ip>:3000/mcp.

Nginx reverse proxy (рекомендуется)

Позволяет закрыть прямой доступ к порту 3000 и выставить наружу только 443/80.

server {
    listen 443 ssl;
    server_name weather-mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/weather-mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/weather-mcp.example.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_read_timeout 30s;
    }
}

После этого можно держать порт 3000 закрытым в firewall и обращаться к https://weather-mcp.example.com/mcp.

Firewall

Если Nginx не используется и порт открыт напрямую — ограничьте доступ по IP:

# UFW пример
ufw allow from <trusted-ip> to any port 3000
ufw deny 3000

Управление контейнером

# Посмотреть логи (включая тики планировщика)
docker compose logs -f

# Перезапустить
docker compose restart

# Обновить после git pull
git pull && docker compose up -d --build

# Остановить (данные БД сохраняются в ./data/)
docker compose down

# Остановить и удалить данные БД
docker compose down && rm -rf data/

Контейнер настроен на restart: unless-stopped — поднимается автоматически после перезагрузки сервера.

Персистентность базы данных планировщика

Планировщик хранит историю наблюдений в SQLite (weather.db). Без volume файл живёт внутри контейнера и пропадает при docker compose down или пересборке образа.

docker-compose.yml уже настроен на монтирование ./data/weather.db — достаточно создать директорию перед первым запуском:

mkdir -p data

Путь к файлу управляется переменной WEATHER_DB_PATH в .env. Менять не нужно, если устраивает ./data/weather.db.

MCP endpoint для клиента

{
  "mcpServers": {
    "yandex-weather": {
      "url": "http://<vds-ip>:3000/mcp"
    }
  }
}

Или с Nginx:

{
  "mcpServers": {
    "yandex-weather": {
      "url": "https://weather-mcp.example.com/mcp"
    }
  }
}

Ошибки

Ошибки возвращаются в едином формате:

{
  "error": {
    "code": "AUTH_ERROR",
    "message": "Yandex Weather API rejected the API key",
    "details": {}
  }
}

Поддержанные коды: CONFIGURATION_ERROR, VALIDATION_ERROR, AUTH_ERROR, RATE_LIMITED, NOT_FOUND, TIMEOUT, NETWORK_ERROR, INVALID_JSON, UNEXPECTED_RESPONSE, UNSUPPORTED_API_PARAMETER, YANDEX_API_ERROR.

Тестирование

npm test
npm run typecheck

Тесты покрывают:

• валидацию координат;

• маппинг погодных состояний;

• отсутствующий API-ключ;

• ошибку API;

• работу кэша;

• нормализацию ответа Яндекс Погоды.

Ограничения

• Сервер не делает геокодинг по названию города.

• Набор полей зависит от тарифа и endpoint Яндекс Погоды.

• Кэш хранится только в памяти процесса.

• HTTP healthcheck проверяет живой процесс и конфигурацию, но не дергает внешний API Яндекс Погоды.

Roadmap второго этапа

• геокодинг по названию города;

• хранение избранных локаций;

• Prometheus-метрики;

• Grafana dashboard;

• rate limiting;

• persistent cache через SQLite/Redis;

• поддержка нескольких weather-провайдеров;

• алерты: дождь, мороз, сильный ветер;

• интеграция с Home Assistant.