aemet-mcp

# aemet-mcp

MCP server that exposes public weather data from [AEMET](https://www.aemet.es)
(Agencia Estatal de Meteorología, Spain) to AI agents and MCP-compatible
clients.

Three tools, well-typed, backed by AEMET's official OpenData API:

- **`get_municipality_forecast`** — daily forecast (up to 7 days) for a
  Spanish municipality, by INE code.
- **`get_station_observation`** — last ~12h of hourly observation data
  (temperature, wind, precipitation…) from a weather station.
- **`get_weather_warnings`** — active weather warnings (CAP alerts) for a
  region or all of Spain.

## Prerequisites

- Node.js 20+
- A free AEMET OpenData API key: request one at
  https://opendata.aemet.es/centrodedescargas/altaUsuario

## Installation

No install needed — run it directly with `npx`:

```bash
npx -y @mmillan76/aemet-mcp
```

The server communicates over stdio, so it's meant to be launched by an MCP
client rather than run standalone in a terminal.

## Configuration

The server reads the API key from the `AEMET_API_KEY` environment variable.
It exits with an error at startup if it's missing.

### Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aemet": {
      "command": "npx",
      "args": ["-y", "@mmillan76/aemet-mcp"],
      "env": {
        "AEMET_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Any other MCP client that supports stdio servers works the same way — point
it at `npx -y @mmillan76/aemet-mcp` with `AEMET_API_KEY` set in the environment.

## Local development

```bash
git clone https://github.com/mmillan76/aemet-mcp.git
cd aemet-mcp
npm install
cp .env.example .env   # fill in AEMET_API_KEY
npm run build
```

Test tool calls interactively with the
[MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

(the Inspector reads `AEMET_API_KEY` from your shell environment, so export
it — or source `.env` — before running the command above)

## Notes on the AEMET API

AEMET OpenData uses a two-step pattern on every endpoint: the first request
returns a JSON envelope with a `datos` URL, not the actual data; a second
request to that URL returns the real payload. This server hides that detail
— tools just return the final data. Rate limits apply per API key; if you
hit them, the tool returns a clear error instead of retrying silently.

## License

MIT — see [LICENSE](./LICENSE).