Skip to main content
Glama

portugal-fuel-ev-mcp

WARNING

Deprecated — use portugal-mcp instead. This server now lives on as the energia feature of portugal-mcp, together with IPMA weather, INE, Banco de Portugal, Parliament, public contracts and more. Install with uvx portugal-mcp (add PORTUGAL_MCP_FEATURES=energia to load only this part). Tool names: all tool names are unchanged. This repository gets no further updates.

MCP server that answers "where is the cheapest place to fill up / charge near me in Portugal?", for combustion cars and electric cars, so Claude (or any MCP client) can look it up from official open data.

Read-only, no keys, no account. Fuel prices come from DGEG's official price site; EV chargers, live status and prices come from the MOBI.E network feeds on Portugal's National Access Point. Not affiliated with DGEG, MOBI.E or IMT.

Tools

fuel_prices

Cheapest stations for one fuel type, cheapest first.

Parameters:

  • fuel_type — a DGEG fuel name or id ("Gasóleo simples", "Gasolina simples 95", "Gasolina 98", "GPL Auto"...) or plain words: "diesel", "petrol", "95", "98", "lpg", "cng"

  • district — e.g. "Lisboa", "Porto", "Faro" (case- and accent-insensitive)

  • municipality — e.g. "Sintra", "Évora" (overrides district)

  • lat / lon + radius_km — search around a point (default radius 10 km)

  • brand — only one brand, e.g. "Galp", "Prio"

  • limit — how many stations (default 10, max 50)

With no area it searches all of Portugal. Each station has: price (EUR per litre, or per kg/m³ for gas), brand, name, address, municipality, coordinates, distance (when searching around a point) and the station's last price update. The result also gives how many stations matched and the min/median/max price.

fuel_station_detail

One station: every fuel it sells with price and last update, opening hours, services and payment methods.

fuel_types

The DGEG fuel types (id, name, unit) and the districts. Only needed when unsure which fuel name to use.

ev_chargers

Public charging sites near a point, nearest first, with live status and published prices.

Parameters:

  • lat / lon — where to search

  • radius_km — default 5, max 100

  • min_power_kw — e.g. 50 for fast DC

  • connector — "CCS", "Type 2", "CHAdeMO", "CEE", or "DC" / "AC"

  • available_only — only points that are free right now

  • limit — sites to return (default 10, max 50)

Each site has: operator, address, distance, opening hours and its matching points. Each point has: live status (available, in use, out of order...), maximum power, connectors and the price the feed publishes (per_kwh, per_minute, per_session, in EUR). The result also says how fresh the data is.

ev_charger_detail

One charging site by site id, point id or EVSE id: all its points with status, power, connectors and price, plus the operator's contact, opening hours and how you can start a charge (app, RFID card, credit card...).

Related MCP server: @cyanheads/openchargemap-mcp-server

About EV prices

The prices are the rates that the MOBI.E status feed publishes for each charging point: a pricing type (per kWh, per minute of charging, per session, or "other", such as parking time) and an amount. They may not be the whole bill:

  • The feed does not say which tariff it is (regular, or ad hoc / pay at the charger), nor whether VAT is included. A spot check against MOBI.E's own tariff list found that where a point has an ad hoc tariff the feed usually carries that one; elsewhere it carries the operator's regular tariff.

  • On the MOBI.E network the operator's tariff is only the charging point's fee. When you pay with a MOBI.E card or app, your provider (CEME) adds its own energy price, plus network access charges, the MOBI.E management fee and taxes.

Every ev_chargers and ev_charger_detail result carries this note (price_note). Use the prices to compare chargers, and check the operator's app or your provider for the final cost.

Install

Quickest (needs uv): no clone needed, it runs straight from PyPI.

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

For Claude Desktop, use "command": "uvx", "args": ["portugal-fuel-ev-mcp"].

From source:

Requires Python 3.10+.

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

On Windows, if you keep code in a cloud-synced folder (Google Drive, OneDrive), create the virtual environment outside it: sync clients drop desktop.ini files into folders, which can crash packages on startup.

Add to Claude Code

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

Add to Claude Desktop

Merge claude_desktop_config.snippet.json into your Claude Desktop claude_desktop_config.json, then restart Claude Desktop:

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

First EV call is slow

The MOBI.E feeds are large (about 180 MB for the inventory, 40 MB for the live status) and are not compressed. The first EV call of the day downloads them, which takes one to three minutes depending on the connection and on MOBI.E's server. The server reads them as they stream in (it never holds the whole file in memory) and keeps a compact cache of about 1 MB, so later calls take milliseconds.

  • The inventory is refreshed at most every 24 hours, and the live status every 10 minutes, only when a tool needs them. Each result's data_freshness says when the data was published and fetched.

  • To download ahead of time (for example if your client times out on long calls), run:

    python -m portugal_fuel_ev_mcp.server --refresh
  • The cache lives in your user cache folder (via platformdirs). Set PORTUGAL_FUEL_EV_CACHE_DIR to use another folder.

  • If a refresh fails, the server keeps using the last cache and says so in data_freshness.warnings.

Fuel prices are fetched live from DGEG on each call (cached for 10 minutes).

Data sources and licences

Data

Source

Terms

Fuel prices, stations, opening hours

DGEG, Preços dos Combustíveis Online (JSON API .../api/PrecoComb/)

DGEG's site says the information is free and can be used freely; reuse must name DGEG as the source, show the date and time of the last price update, and reproduce the information faithfully. The tools return source and each price's last_update for that reason.

EV charging sites, points, connectors, live status and prices

MOBI.E, via Portugal's National Access Point (NAP, IMT): https://pgm.mobie.pt/integration/nap/evChargingInfra and .../evActualStatus (DATEX II 3.3 XML)

Listed on the NAP (datasets 148 and 149) as "Livre acesso" (open access), with no separate licence document. Credit "MOBI.E / NAP Portugal" when you reuse the data.

Prices are posted by station operators and charging operators; they can be wrong or out of date. Check at the pump or in the charger's app.

The DGEG endpoints are the ones used by the Home Assistant integration netsoft-ruidias/ha-custom-component-precoscombustiveis and by GeiserX/Pumperly. The DATEX II parsing follows the notes in CarregaErvilhas/nap-dashboard and mobilidade-dados-pt/carregamento-pt.

How it works

  • Fuel: PesquisarPostos returns every station selling one fuel type in an area, with price ("1,899 €", turned into 1.899), coordinates and last update; for a point search the server fetches the whole country (about 1 MB) and filters by distance. GetDadosPosto gives one station's details.

  • EV: the two DATEX II feeds are parsed incrementally with Python's built-in xml.etree.ElementTree.XMLPullParser, one charging site at a time. Status and prices are joined to the inventory by (site id, point id), because some operators reuse bare point ids across sites. Requests send If-None-Match, so an unchanged feed is not downloaded again.

If a source changes or is down, tools return {"error": ...} instead of wrong data.

License

MIT

Available Tools

5 tools
ev_charger_detailA

Everything about one MOBI.E charging site: all its points with live status, power, connectors and price, plus operator contact, opening hours and accepted authentication (app, RFID card, credit card...).

Use after ev_chargers. Accepts a site_id (e.g. "EZC-AMD-00051"), a point_id (e.g. "AMD-00051-1") or an EVSE id (e.g. "PTEZCEAMD00051*1").

Inputs: site_or_point_id (required). Returns: object

ev_chargersA

Public EV charging sites near a point in Portugal (MOBI.E network), nearest first, with live status and the price the network publishes for each charging point.

Use for "where can I charge near X?", "fast chargers near me", "is there a free CCS charger nearby?". Needs coordinates; if the user gives a place name, use known coordinates for it. Covers mainland Portugal, Azores and Madeira.

Args: lat, lon: Point to search around (WGS84). radius_km: Search radius (default 5, max 100). min_power_kw: Only points that can deliver at least this power, e.g. 50 for fast DC. connector: "CCS" (CCS2), "Type 2", "CHAdeMO", "CEE", or "DC" / "AC". available_only: Only points whose live status is "available" right now. limit: Max sites to return (default 10, max 50).

Each site: operator, address, distance_km, opening hours and its matching points, each with status (available, in use, out of order...), max power, connectors and price (per_kwh / per_minute / per_session in EUR, from the feed). IMPORTANT: these are the charging operator's published fees and may not be the whole bill: see price_note and tell the user. data_freshness says how old the inventory and live status are. The first call of the day downloads ~220 MB from MOBI.E and can take 1-3 minutes.

Inputs: lat (required), lon (required), limit, connector, +3 more. Returns: object

fuel_pricesA

Cheapest fuel stations in Portugal for one fuel type, cheapest first (official DGEG prices).

Use for "where is diesel/petrol/LPG cheapest in Lisboa / near me / in Braga?". Give an area as a district, a municipality, or a point (lat + lon, with radius_km); with no area it searches all of Portugal. Names are case- and accent-insensitive ("evora" works).

Args: fuel_type: A DGEG fuel name or id, e.g. "Gasóleo simples" (regular diesel, 2101), "Gasolina simples 95" (regular 95 petrol, 3201), "Gasolina 98", "GPL Auto" (LPG), or plain words: "diesel", "petrol", "95", "98", "lpg", "cng". See fuel_types() for the full list. district: Portuguese district, e.g. "Lisboa", "Porto", "Faro". municipality: Municipality (concelho), e.g. "Sintra", "Vila Nova de Gaia". Overrides district. lat, lon: A point (WGS84). Results get distance_km and are limited to radius_km. radius_km: Search radius around lat/lon (default 10). brand: Only this brand (substring match), e.g. "Galp", "Prio", "Intermarché". limit: How many stations to return (default 10, max 50).

Each station: price_eur (per litre, or per kg/m3 for gas), brand, name, address, municipality, distance_km (with lat/lon), coordinates and last_update (the station's last price update). Also returns how many stations matched and the min/median/max price. Always mention the source (DGEG) and the last_update when quoting prices.

Inputs: fuel_type (required), lat, lon, brand, +4 more. Returns: object

fuel_station_detailA

Full details of one fuel station: every fuel it sells with price and last update, opening hours, services (car wash, shop, tyre air...) and payment methods.

Use after fuel_prices, with a station id from its results.

Inputs: station_id (required). Returns: object

fuel_typesA

List DGEG fuel types (id, name, unit) and the districts accepted by fuel_prices.

Only needed when unsure which fuel name to pass; fuel_prices also understands "diesel", "petrol", "95", "98", "lpg".

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 5 tools

    Disambiguation5/5

    The set cleanly splits into two domains: fuel stations (fuel_prices, fuel_station_detail, fuel_types) and EV charging (ev_chargers, ev_charger_detail). Search tools and detail tools are explicitly paired, and fuel_types is clearly a lookup helper. No two tools appear to do the same thing.

    Naming Consistency4/5

    All names use snake_case and follow a domain_action or domain_resource pattern. Minor inconsistency exists between plural list tools (fuel_prices, ev_chargers) and singular detail tools (fuel_station_detail, ev_charger_detail), and fuel_types is a helper rather than an action. Still predictable and readable.

    Tool Count5/5

    Five tools is well-scoped for a specialized Portugal fuel/EV charging server. Each tool has a clear role: two search tools, two detail tools, and one reference/lookup tool. Nothing feels redundant or missing from the count perspective.

    Completeness4/5

    The surface covers the core lifecycle: find fuel stations, inspect a station, list fuel types, find EV chargers, and inspect a charging site. A minor gap is that EV charger search requires coordinates and lacks the district/municipality convenience offered by fuel_prices. Overall complete enough for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to look up official Brazilian fuel station information from a hosted service, paying per query with prepaid credits, across any MCP-compatible client.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to query live fuel prices across NSW and Tasmania from the API.NSW Fuel API, finding the cheapest or nearest stations around a suburb, postcode or coordinates, listing all current prices at a given station, searching stations by name, brand or location, and looking up fuel type codes. Reference data is cached for 24 hours to conserve monthly API quota.
      87 PyPI
      MIT