aemet-mcp

aemet-mcp

一个 Model Context Protocol 服务，让 LLM 客户端——Claude Desktop、Cursor、Windsurf、Zed、自定义 Agent——能够使用 AEMET（国家气象局）的真实数据回答有关西班牙天气的问题。

西班牙语版本 · 提供八种工具的 MCP 服务，用于获取 AEMET 的开放数据。 需要 Node.js 20.19 或更高版本。

基于 aemet-client 构建， 与 snowy.es 使用的是同一款 TypeScript SDK。

通过 stdio 在本地运行——无需托管基础设施，也没有共享 API 密钥。 每位用户都需要提供自己的免费 AEMET 密钥。

获取 AEMET API 密钥

免费，只需约一分钟：

1. 打开 opendata.aemet.es/centrodedescargas/altaUsuario
2. 输入你的电子邮件地址
3. 对方会以 JWT 格式发送密钥，复制即可

在 Claude Desktop 中使用

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json， 或在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json，并添加：

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

重启 Claude Desktop，然后提问：“本周马德里的天气预报是什么？”、“加泰罗尼亚目前有生效的天气预警吗？”、 “去年 8 月洛格罗尼奥下了多少雨？” 或 “拉孔查海滩的水温是多少？”。

在 Cursor / Windsurf / Zed 中使用

配置对象相同——所有支持 MCP 的客户端都接受 { command, args, env } 格式。请查阅相应文档，了解配置文件的位置。

工具

get_forecast

获取西班牙 8000 多个市镇的 AEMET 官方天气预报。

参数	类型	说明
location	string	名称（"Madrid"、"Logroño"、"A Coruña"）或 5 位 INE 代码
days	integer 1-7（可选）	默认值为 3。当 granularity="hourly" 时忽略此参数
granularity	"daily" | "hourly"	每日摘要或未来约 40 小时的逐小时预报

get_warnings

针对某个自治区或全国范围的生效 CAP（通用预警协议）预警。

参数	类型	说明
area	string	"Cataluña"、"Madrid"、"73"（拉里奥哈）、"esp" …
language	"es" | "en" | "ca" | "gl" | "eu" | "any"	首选的预警语言。默认值为 "es"
minSeverity	"Minor" | "Moderate" | "Severe" | "Extreme"	筛除低于此严重程度的预警

get_nearest_observation

从距离指定地点最近的 AEMET 气象站获取最新实时观测数据（温度、湿度、风、降水、 气压、能见度）。

参数	类型	说明
location	string	市镇名称、INE 代码或十进制度坐标对（"40.4168,-3.7038"）

get_climate_history

某个地点最近的 AEMET 气象站提供的历史气候数据：可查询日期范围内的每日记录，也可查询该站的长期月平均值。

参数	类型	说明
location	string	市镇名称、INE 代码或十进制坐标对
mode	"range" | "normals"	"range"（默认）读取每日记录。"normals" 读取月平均值
from	string	YYYY-MM-DD。"range" 模式必填
to	string (optional)	YYYY-MM-DD，默认为今天

AEMET 将每日气候查询限制为每次 186 天，因此超出该范围的请求会被拒绝，并说明原因。超过一个月的日期范围会按月汇总（最高／最低均值、极值、总降水量、降雨天数），而不是逐日列出。

get_beach_forecast

AEMET 在泳季期间覆盖的 591 个海滩中任意一个的三日预报：包括分上午和下午时段的天空状况、风况和海浪情况，以及最高气温、水温、体感温度和 UV 指数。

参数	类型	说明
location	string	海滩名称（"La Concha"、"Es Trenc"）、沿海市镇（用于列出该市镇的海滩）或 7 位 AEMET 海滩代码
municipality	string (optional)	市镇或省份，用于区分名称相同的海滩
days	integer 1-3	默认为 3

名称匹配时不区分重音符号，并能容忍人们实际使用的拼写方式（"la kontxa"、"playa de la concha, suances"）。如果一个名称匹配多个海滩，服务会返回候选项及其代码。泳季之外，AEMET 会停止发布预报，该工具也会说明这一点。

get_mountain_forecast

AEMET 面向其覆盖的 9 个区域发布的山区公告：分区预报、零度层高度、自由大气风况，以及注明名称和海拔的避难所与山口的气温。也可提供过去 24 小时的数据。

Argument	Type	Notes
area	string	区域名称或代码：Picos de Europa（peu1）、Pirineo Navarro（nav1）、Pirineo Aragonés（arn1）、Pirineo Catalán（cat1）、Ibérica Riojana（rio1）、Ibérica Aragonesa（arn2）、Sierras de Guadarrama y Somosierra（mad2）、Sierra de Gredos（gre1）、Sierra Nevada（nev1）
mode	"forecast" | "past"	预报（默认）或过去 24 小时的数据
day	integer 0-3	预报的未来天数，默认 0（今天）

也支持常见别名："Guadarrama"、"Moncayo"、"Urbión"、"Peñibética"、 "Val d'Aran"、"Gredos"。

get_maritime_forecast

AEMET 的海洋公告：沿海海域（8 个区域）和远海（3 个区域），包含预警、 天气形势、分区预报以及次日趋势。

Argument	Type	Notes
area	string	区域、沿海省份或地区（"Gipuzkoa"、"Girona"、"Mar Menor"、"Gran Sol"、"Alborán"），或代码：40-47 表示沿海，0-2 表示远海
product	"coastal" | "high_seas"	当某个名称同时对应两种产品时，强制指定其中一种

AEMET 将风况、海况和能见度作为每个区域的一段文本发布，因此该工具会原样传递 这些文本，而不会猜测并拆分。

get_air_quality

AEMET 农村 EMEP/VAG/CAMP 参考网络的背景污染数据： 区域背景空气质量，并非城市空气质量。

Argument	Type	Notes
station	string (optional)	站点名称或两位代码（"Campisábalos"、"Doñana"、"09"）
location	string (optional)	市镇、INE 代码或坐标；可解析最近的站点并报告距离

测量数据包含 AEMET 的验证代码，无效值会被标记，以免模型将其作为真实读数引用。

缓存

AEMET 会限制其 API 的请求频率，而且部分响应数据量很大：仅气象站列表就有 926 条记录，服务器每次查询气候数据时都会读取该列表。因此，默认情况下，响应会按端点缓存在内存中，时长为 10 分钟。

若要更改缓存时长，请在与 API 密钥相同的 env 块中设置 AEMET_CACHE_TTL，单位为秒；将其设为 0 则会关闭缓存：

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

缓存位于服务进程中，因此 MCP 客户端关闭服务时，缓存也会消失。如果需要共享缓存或持久化缓存，请通过 clientConfig 传入自己的 cache 适配器。

编程方式使用

如果你正在构建自己的 MCP 集成，也可以将此服务作为库使用：

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());

你可以传入现有的 AemetClient（例如，配置了 Redis 缓存的客户端），而不是 API 密钥：

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

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

市镇名称的解析方式

由于此包内嵌了由 aemet-client 提供的完整 INE 市镇数据集（8000 多条记录），location 支持自由格式的名称。搜索 "logrono"、"Logroño" 或 "26089" 都会解析到同一地点。十进制度坐标会解析到最近的市镇。

对于自治区，也支持常见别名："Cataluña"、"catalunya"、"Catalonia"、"Euskadi"、"País Vasco"、"Comunitat Valenciana" 等。

许可证

MIT © Jorge Carrera