Portugal Fuel & EV Charging

portugal-fuel-ev-mcp

MCP 服务，可回答“在葡萄牙，我附近哪里加油或充电最便宜？”，适用于燃油车和电动汽车，让 Claude（或任何 MCP 客户端）能够通过官方开放数据查询信息。

**只读，无需密钥，无需账户。**燃油价格来自 DGEG 官方价格网站；电动汽车充电桩、实时状态和价格来自葡萄牙国家接入点上的 MOBI.E 网络数据源。与 DGEG、MOBI.E 或 IMT 均无关联。

工具

fuel_prices

按价格从低到高列出一种燃油类型的最便宜加油站。

参数：

• fuel_type — DGEG 燃油名称或 ID（"Gasóleo simples"、"Gasolina simples 95"、"Gasolina 98"、"GPL Auto"……）或普通词语："diesel"、"petrol"、"95"、"98"、"lpg"、"cng"
• district — 例如 "Lisboa"、"Porto"、"Faro"（不区分大小写和重音符号）
• municipality — 例如 "Sintra"、"Évora"（优先于 district）
• lat / lon + radius_km — 搜索指定地点周边（默认半径为 10 km）
• brand — 仅限一个品牌，例如 "Galp"、"Prio"
• limit — 返回的加油站数量（默认 10，最多 50）

如果未指定区域，则搜索葡萄牙全境。每个加油站包含：价格（每升欧元；气体燃料按每千克或每立方米计）、品牌、名称、地址、市镇、坐标、距离（搜索指定地点周边时）以及该站最近一次价格更新时间。结果还会显示符合条件的加油站数量，以及最低价、中位价和最高价。

fuel_station_detail

单个加油站的详情：该站出售的所有燃油及其价格和最近更新时间、营业时间、服务和付款方式。

fuel_types

DGEG 燃油类型（ID、名称、单位）和地区。只有不确定要使用哪个燃油名称时才需要查询。

ev_chargers

按距离从近到远列出指定地点附近的公共充电站点，以及实时状态和公布的价格。

参数：

• lat / lon — 搜索地点
• radius_km — 默认 5，最大 100
• min_power_kw — 例如 50 表示直流快充
• connector — "CCS"、"Type 2"、"CHAdeMO"、"CEE" 或 "DC" / "AC"
• available_only — 仅返回当前空闲的充电点
• limit — 返回的站点数量（默认 10，最多 50）

每个站点包含：运营商、地址、距离、营业时间及匹配的充电点。每个充电点包含：实时状态（可用、使用中、故障等）、最大功率、连接器，以及数据源公布的价格（per_kwh、per_minute、per_session，单位为欧元）。结果还会注明数据的新鲜度。

ev_charger_detail

根据站点 ID、充电点 ID 或 EVSE ID 查询单个充电站点：该站点的所有充电点及其状态、功率、连接器和价格，以及运营商联系方式、营业时间和启动充电的方式（应用、RFID 卡、信用卡等）。

关于电动汽车充电价格

价格是 MOBI.E 状态数据源为每个充电点公布的 rates：包括计价方式（按 kWh、充电分钟、每次充电或“其他”，例如停车时间）和金额。这些价格未必涵盖全部费用：

• 数据源未注明费率类型（标准费率还是即插即付费率），也未说明是否含增值税。与 MOBI.E 自有费率列表进行抽查对比后发现，若充电点提供即插即付费率，数据源通常会收录该费率；否则则会收录运营商的标准费率。
• 在 MOBI.E 网络中，运营商的费率仅是充电点的费用。使用 MOBI.E 卡或应用付款时，您的服务提供商（CEME）还会收取自己的电价、网络接入费、MOBI.E 管理费和税费。

每个 ev_chargers 和 ev_charger_detail 结果都会附带此说明（price_note）。请使用这些价格比较充电桩，并通过运营商的应用或您的服务提供商确认最终费用。

安装

最快方式（需要 uv）：无需克隆，直接从 PyPI 运行。

claude mcp add portugal-fuel-ev -- uvx portugal-fuel-ev-mcp

对于 Claude Desktop，请使用 "command": "uvx", "args": ["portugal-fuel-ev-mcp"]。

从源代码安装：

需要 Python 3.10+。

git clone https://github.com/ThiagoJacobLannes/portugal-fuel-ev-mcp
cd portugal-fuel-ev-mcp
python -m pip install -e .

在 Windows 上，如果代码位于云同步文件夹（Google Drive、OneDrive）中，请在该文件夹之外创建虚拟环境：同步客户端会在文件夹中放入 desktop.ini 文件，这可能导致软件包在启动时崩溃。

添加到 Claude Code

claude mcp add portugal-fuel-ev -- python -m portugal_fuel_ev_mcp.server

添加到 Claude Desktop

将 claude_desktop_config.snippet.json 合并到 Claude Desktop 的 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "portugal-fuel-ev": {
      "command": "python",
      "args": ["-m", "portugal_fuel_ev_mcp.server"]
    }
  }
}

首次调用 EV 时速度较慢

MOBI.E 数据源文件较大（库存数据约 180 MB，实时状态约 40 MB），且未压缩。每天首次调用 EV 时会下载这些文件，根据网络连接和 MOBI.E 服务的情况，耗时一到三分钟。服务会在数据流传入时读取文件（不会将整个文件保存在内存中），并缓存约 1 MB 的精简数据，因此后续调用只需几毫秒。

• 库存数据最多每 24 小时刷新一次，实时状态每 10 分钟刷新一次，且仅在工具需要时刷新。每个结果的 data_freshness 会说明数据的发布时间和获取时间。

• 如需提前下载（例如客户端在长时间调用时超时），请运行：

  python -m portugal_fuel_ev_mcp.server --refresh
  

• 缓存位于用户缓存文件夹中（通过 platformdirs 获取）。设置 PORTUGAL_FUEL_EV_CACHE_DIR 可使用其他文件夹。

• 如果刷新失败，服务会继续使用上次的缓存，并在 data_freshness.warnings 中说明。

每次调用时都会从 DGEG 实时获取燃油价格（缓存 10 分钟）。

数据来源和许可

数据	来源	条款
燃油价格、加油站、营业时间	DGEG，Preços dos Combustíveis Online（JSON API .../api/PrecoComb/）	DGEG 网站说明，信息可免费自由使用；再次使用时必须注明 DGEG 为来源、显示最近一次价格更新的日期和时间，并忠实呈现信息。工具会因此返回 source 和每个价格的 last_update。
EV 充电站点、充电点、连接器、实时状态和价格	MOBI.E，通过葡萄牙国家接入点（NAP, IMT）：https://pgm.mobie.pt/integration/nap/evChargingInfra 和 .../evActualStatus（DATEX II 3.3 XML）	在 NAP（数据集 148 和 149）上列为“Livre acesso”（开放访问），没有单独的许可文件。再次使用数据时，请注明“MOBl.E / NAP Portugal”。

价格由加油站运营商和充电运营商发布，可能有误或已过时。请在加油泵处或充电器的应用中核实。

DGEG 端点由 Home Assistant 集成 netsoft-ruidias/ha-custom-component-precoscombustiveis 和 GeiserX/Pumperly 使用。DATEX II 解析遵循 CarregaErvilhas/nap-dashboard 和 mobilidade-dados-pt/carregamento-pt 中的说明。

工作原理

• 燃油：PesquisarPostos 会返回某个区域内销售一种燃油的所有加油站，包括价格（"1,899 €"，转换为 1.899）、坐标和最后更新时间；按位置点搜索时，服务会获取整个国家的数据（约 1 MB），再按距离筛选。GetDadosPosto 会提供单个加油站的详细信息。
• **电动汽车：**两个 DATEX II 数据源会使用 Python 内置的 xml.etree.ElementTree.XMLPullParser 增量解析，每次处理一个充电站点。状态和价格会按（站点 ID、位置点 ID）与库存数据关联，因为有些运营商会在不同站点重复使用未限定的点 ID。请求会发送 If-None-Match，因此数据源未变化时不会再次下载。

如果数据源发生变化或不可用，工具会返回 {"error": ...}，而不是错误数据。

许可证

MIT