Skip to main content
Glama
relativismofisico

weather-mcp

by relativismofisico
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

weather-mcp

Servidor MCP para consultar el tiempo en cualquier ciudad del mundo, usando la API gratuita de Open-Meteo. Sin registro, sin API key.

Arquitectura y componentes

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code / IA                         │
│                  (cliente MCP — cualquier host)                 │
└────────────────────────┬────────────────────────────────────────┘
                         │  stdio (JSON-RPC)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      weather-mcp (este servidor)                │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    MCP Server                           │   │
│   │         @modelcontextprotocol/sdk  +  Zod               │   │
│   │                                                         │   │
│   │  ┌─────────────────┐  ┌─────────────────┐              │   │
│   │  │get_current_      │  │  get_forecast   │              │   │
│   │  │weather           │  │  (1–7 días)     │              │   │
│   │  └────────┬────────┘  └────────┬────────┘              │   │
│   │           │                    │                        │   │
│   │  ┌────────▼────────────────────▼────────┐              │   │
│   │  │         get_uv_and_air               │              │   │
│   │  │    (índice UV + calidad del aire)    │              │   │
│   │  └──────────────────┬───────────────────┘              │   │
│   │                     │                                   │   │
│   │  ┌──────────────────▼───────────────────┐              │   │
│   │  │           Geocoding helper            │              │   │
│   │  │  ciudad → latitud / longitud          │              │   │
│   │  └──────────────────┬───────────────────┘              │   │
│   └─────────────────────┼───────────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────────┘
                          │  HTTPS (fetch nativo Node 18+)
          ┌───────────────┼───────────────────────┐
          ▼               ▼                       ▼
┌──────────────┐ ┌────────────────┐ ┌─────────────────────────┐
│  Geocoding   │ │    Forecast    │ │      Air Quality         │
│  API         │ │    API         │ │      API                 │
│  open-meteo  │ │  open-meteo   │ │  air-quality.open-meteo  │
└──────────────┘ └────────────────┘ └─────────────────────────┘

Flujo de una consulta

IA: "¿Qué tiempo hace en Bogotá?"
        │
        ▼
1. MCP llama get_current_weather({ city: "Bogotá" })
        │
        ▼
2. geocodeCity("Bogotá")
   → GET geocoding-api.open-meteo.com/v1/search
   ← { latitude: 4.71, longitude: -74.07, country: "Colombia" }
        │
        ▼
3. GET api.open-meteo.com/v1/forecast
   ← temperatura, humedad, viento, código WMO, precipitación
        │
        ▼
4. Respuesta formateada en texto legible
   → IA la presenta al usuario

Related MCP server: Weather MCP Server

Estructura del proyecto

weather-mcp/
├── src/
│   ├── index.ts          # Entrada: registro de herramientas MCP y arranque del servidor
│   ├── handlers.ts       # Lógica de negocio de las 3 herramientas (testeable de forma aislada)
│   ├── weather.ts        # Utilidades puras: geocodeCity, describeWeather, WMO_CODES
│   └── __tests__/
│       ├── weather.test.ts    # Tests de geocodificación y códigos WMO (9 tests)
│       └── handlers.test.ts   # Tests de herramientas con fetch mockeado (31 tests)
├── vitest.config.ts      # Configuración de tests y umbrales de cobertura (≥80%)
├── tsconfig.json
└── package.json

Herramientas utilizadas

Herramienta

Versión

Propósito

TypeScript

5.8

Lenguaje principal

@modelcontextprotocol/sdk

1.13

Protocolo MCP (servidor stdio)

Zod

3.24

Validación de esquemas de herramientas

tsx

4.19

Ejecución directa de TypeScript en desarrollo

Vitest

3.x

Framework de tests unitarios

@vitest/coverage-v8

3.x

Cobertura de código con motor V8

Open-Meteo Forecast API

—

Datos meteorológicos actuales y pronóstico

Open-Meteo Geocoding API

—

Conversión ciudad → coordenadas

Open-Meteo Air Quality API

—

Índice UV y calidad del aire

Instalación

Requisitos

  • Node.js 18 o superior

  • Claude Code CLI (npm install -g @anthropic-ai/claude-code)

Pasos

# 1. Clonar el repositorio
git clone https://github.com/relativismofisico/weather-mcp.git
cd weather-mcp

# 2. Instalar dependencias y compilar
npm install
npm run build

# 3. Registrar en Claude Code (global — disponible en cualquier proyecto)
claude mcp add weather --transport stdio --scope user -- node /ruta/absoluta/weather-mcp/dist/index.js

En Windows usa la ruta completa con barras normales: node C:/Users/TuUsuario/weather-mcp/dist/index.js

Verificar la instalación

claude mcp list
# weather: node .../dist/index.js - ✔ Connected

Uso desde una IA

Una vez registrado, abre una nueva conversación en Claude Code. Las herramientas estarán disponibles automáticamente. Puedes pedirle a la IA:

Tiempo actual

"¿Qué tiempo hace en Buenos Aires?" "Dame la temperatura actual en Tokio" "¿Está lloviendo en Londres ahora mismo?"

Pronóstico

"Dame el pronóstico de 7 días para Ciudad de México" "¿Cómo va a estar el tiempo en París esta semana?"

UV y calidad del aire

"¿Cuál es el índice UV en Medellín hoy?" "¿La calidad del aire en Beijing es buena?"

Ejemplo de respuesta

📍 Buenos Aires, Ciudad Autónoma de Buenos Aires, Argentina
🕐 2026-06-29T14:00 (hora local)  ☀️ Día

🌡️  Temperatura:      18°C  (sensación 16°C)
💧 Humedad:           65%
🌬️  Viento:           22 km/h  (dirección 180°)
🌧️  Precipitación:    0 mm
☁️  Cielo:            Parcialmente nublado

Herramientas MCP expuestas

get_current_weather

Obtiene el tiempo actual de una ciudad.

Parámetro

Tipo

Descripción

city

string

Nombre de la ciudad (ej. "Madrid", "New York")

Datos devueltos: temperatura, sensación térmica, humedad, velocidad y dirección del viento, precipitación, descripción del cielo (código WMO), si es de día o noche.

get_forecast

Pronóstico diario de hasta 7 días.

Parámetro

Tipo

Descripción

city

string

Nombre de la ciudad

days

number

Días del pronóstico (1–7, por defecto 5)

Datos devueltos por día: temperatura máx/mín, lluvia acumulada, viento máximo, hora de amanecer y atardecer, descripción del cielo.

get_uv_and_air

Índice UV actual y calidad del aire.

Parámetro

Tipo

Descripción

city

string

Nombre de la ciudad

Datos devueltos: índice UV con etiqueta (Bajo / Moderado / Alto / Muy alto / Extremo), AQI (US), PM2.5, PM10, monóxido de carbono.

Desarrollo

# Ejecutar en modo desarrollo (sin compilar)
npm run dev

# Compilar
npm run build

# Probar con MCP Inspector
npx @modelcontextprotocol/inspector
# → seleccionar "stdio", comando: node dist/index.js

Tests y cobertura

El proyecto usa Vitest con cobertura por V8. Los umbrales mínimos configurados son 80% en todas las métricas; actualmente se alcanza el 100%.

# Ejecutar todos los tests
npm test

# Tests en modo watch (desarrollo)
npm run test:watch

# Tests con reporte de cobertura
npm run test:coverage

Resultado actual

-------------|---------|----------|---------|---------|
File         | % Stmts | % Branch | % Funcs | % Lines |
-------------|---------|----------|---------|---------|
handlers.ts  |     100 |      100 |     100 |     100 |
weather.ts   |     100 |      100 |     100 |     100 |
-------------|---------|----------|---------|---------|
All files    |     100 |      100 |     100 |     100 |

Qué se testea

Módulo

Tests

Casos cubiertos

weather.ts

9

Todos los códigos WMO, fallback para código desconocido, geocodificación exitosa, errores HTTP, ciudad no encontrada, caracteres especiales

handlers.ts

31

Día/noche, ubicación con y sin admin1, todos los rangos UV (Bajo→Extremo) y AQI (Buena→Insalubre), extracción de amanecer/atardecer, precipitación, propagación de errores HTTP en cada API

Los tests mockean fetch globalmente con vi.stubGlobal — no se realizan llamadas reales a la red.

Changelog

v0.2.0 — 2026-06-29

  • Refactorización: extracción de weather.ts (utilidades puras) y handlers.ts (lógica de herramientas) para habilitar tests unitarios sin dependencia del servidor MCP

  • 40 tests unitarios con 100% de cobertura (statements, branches, functions, lines)

  • Configuración de Vitest con umbrales de cobertura ≥ 80%

  • coverage/ excluido del repositorio vía .gitignore

v0.1.0 — 2026-06-29

  • Implementación inicial del servidor MCP con transporte stdio

  • Herramienta get_current_weather: temperatura, humedad, viento, precipitación y descripción del cielo

  • Herramienta get_forecast: pronóstico de 1 a 7 días con amanecer/atardecer

  • Herramienta get_uv_and_air: índice UV y calidad del aire (PM2.5, PM10, CO, AQI)

  • Geocodificación automática de ciudad a coordenadas vía Open-Meteo Geocoding API

  • Descripciones de cielo en español usando códigos WMO

  • Sin API key requerida — 100% gratuito

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/relativismofisico/weather-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server