aemet-mcp

A Model Context Protocol server that lets LLM clients — Claude Desktop, Cursor, Windsurf, Zed, custom agents — answer questions about Spain's weather using real data from AEMET, the State Meteorological Agency.

Versión en español · Servidor MCP con ocho herramientas sobre los datos abiertos de AEMET. Requiere Node.js 20.19 o superior.

Built on top of aemet-client, the same TypeScript SDK that powers snowy.es.

Runs locally over stdio — no hosted infrastructure, no shared API key. Every user supplies their own free AEMET key.

Get an AEMET API key

Free, takes about a minute:

1. Open opendata.aemet.es/centrodedescargas/altaUsuario
2. Enter your email
3. They send you the key as a JWT — copy it

Use it from Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows and add:

{
  "mcpServers": {
    "aemet": {
      "command": "npx",
      "args": ["-y", "aemet-mcp"],
      "env": {
        "AEMET_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Restart Claude Desktop and ask: "What's the weather forecast for Madrid this week?", "Are there any active weather warnings in Catalonia right now?", "How much did it rain in Logroño last August?" or "What's the water temperature at La Concha?".

Use it from Cursor / Windsurf / Zed

Same config object — every MCP-capable client accepts the { command, args, env } shape. See their docs for where the config file lives.

Tools

get_forecast

AEMET's official forecast for any of Spain's 8000+ municipalities.

get_warnings

Active CAP (Common Alerting Protocol) warnings for an autonomous community or the whole country.

get_nearest_observation

Latest real-time observation (temperature, humidity, wind, precipitation, pressure, visibility) from the AEMET station closest to a location.

get_climate_history

Historical climate data from the AEMET station closest to a location: either daily records over a date range or the station's long-term monthly normals.

AEMET caps daily climate queries at 186 days per request, so longer ranges are rejected with a message explaining it. Ranges over a month come back aggregated by month (mean max/min, extremes, total precipitation, rain days) instead of one line per day.

get_beach_forecast

Three-day forecast for any of the 591 beaches AEMET covers during the bathing season: sky, wind and waves split into morning and afternoon, plus maximum temperature, water temperature, thermal sensation and UV index.

Names resolve without accents and tolerate how people actually write them ("la kontxa", "playa de la concha, suances"). When a name matches more than one beach, the server answers with the candidates and their codes. Outside the bathing season AEMET stops publishing and the tool says so.

get_mountain_forecast

AEMET's mountain bulletin for the nine areas it covers: the forecast by section, freezing-level altitudes, free-atmosphere winds, and temperatures at named refuges and passes with their altitude. Also serves the last 24 hours.

Common aliases work: "Guadarrama", "Moncayo", "Urbión", "Peñibética", "Val d'Aran", "Gredos".

get_maritime_forecast

AEMET's marine bulletins: coastal waters (8 areas) and high seas (3 areas), with warnings, the synoptic situation, the forecast per zone and the trend for the following day.

AEMET writes wind, sea state and visibility as a single text per zone, so the tool passes that text through rather than splitting it with guesswork.

get_air_quality

Background pollution from AEMET's rural EMEP/VAG/CAMP reference network: regional background air, not urban air quality.

Measurements carry AEMET's validation codes, and values flagged as invalid are labelled so a model does not quote them as real readings.

Caching

AEMET rate-limits its API and some responses are heavy: the station inventory alone is 926 entries, and the server reads it on every climate query. Responses are therefore cached in memory for 10 minutes by default, per endpoint.

Set AEMET_CACHE_TTL in the same env block as the API key to change it, in seconds, or to 0 to turn caching off:

"env": {
  "AEMET_API_KEY": "paste-your-key-here",
  "AEMET_CACHE_TTL": "1800"
}

The cache lives in the server process, so it disappears when your MCP client closes it. Pass your own cache adapter through clientConfig if you need something shared or persistent.

Programmatic use

If you're building your own MCP integration, the server is also exposed as a library:

import { createServer } from "aemet-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const { server } = createServer({ apiKey: process.env.AEMET_API_KEY });
await server.connect(new StdioServerTransport());

You can pass an existing AemetClient (for example one wired to a Redis cache) instead of an API key:

import { AemetClient } from "aemet-client";
import { createServer } from "aemet-mcp";

const client = new AemetClient({ apiKey, cache: { adapter: redisAdapter } });
const { server } = createServer({ client });

How it resolves municipalities

location accepts free-form names because the package embeds the full INE municipality dataset (8000+ entries) shipped by aemet-client. Searching for "logrono", "Logroño" or "26089" all resolve to the same place. Decimal coordinates resolve to the nearest municipality.

For autonomous communities, common aliases work: "Cataluña", "catalunya", "Catalonia", "Euskadi", "País Vasco", "Comunitat Valenciana", etc.

License

MIT © Jorge Carrera