Pumperly MCP README

pumperly-mcp

A small bridge that exposes any Pumperly instance as an MCP server, so an AI agent can find the cheapest fuel or charging near a place or along a drive, in about 40 countries, mostly in Europe.

Features

Six read-only tools:

Tool	What it answers
`cheapest_fuel_on_route`	Where to fill up between two places, in one call
`find_nearest_stations`	Stations near a place name or coordinates, by distance or price
`get_stations_in_area`	Stations inside a bounding box, cheapest first
`calculate_route`	Driving distance and time between places, with up to 5 stops
`find_route_stations`	Stations along a route geometry you already have
`geocode`	Coordinates for a place name

Four resources: pumperly://fuel-types, pumperly://config, pumperly://stats, pumperly://exchange-rates.
Short answers: station lists are sorted, cut to a limit and summarised (min, median and max price), so a search costs about 1 KB of context.
MCP 2026-07-28 and every earlier version back to 2024-11-05, on the same binary: new clients use server/discover, older ones initialize.
Two transports: stdio, and streamable HTTP on /mcp with a bearer token and origin checks.
Works with the public instance at pumperly.com or your own: set PUMPERLY_URL. No API key.

Every tool only reads, so there is no read-only switch to set.

Install

The npm package downloads the release binary for your platform, checks its SHA-256 against the checksums shipped in the package, and runs it over stdio. It needs Node.js 18 or later.

Claude Code:

Terminal

claude mcp add pumperly -- npx -y pumperly-mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json):

config.json

{
  "mcpServers": {
    "pumperly": { "command": "npx", "args": ["-y", "pumperly-mcp"] }
  }
}

VS Code (.vscode/mcp.json):

config.json

{
  "servers": {
    "pumperly": { "type": "stdio", "command": "npx", "args": ["-y", "pumperly-mcp"] }
  }
}

Codex (~/.codex/config.toml):

toml

[mcp_servers.pumperly]
command = "npx"
args = ["-y", "pumperly-mcp"]

Docker, over stdio:

Terminal

docker run -i --rm -e TRANSPORT=stdio drumsergio/pumperly-mcp:v0.2.0

To use your own Pumperly instance, add PUMPERLY_URL to the environment ("env": { "PUMPERLY_URL": "https://..." } in the JSON configs). For the HTTP transport, see Getting started.

Documentation

Getting started: npm, Docker Compose, building from source, connecting a client
Configuration: environment variables
Usage: tools, resources, the request flow, testing with the Inspector
Related projects: the Pumperly family, other MCP servers, registry listings

License

GPL-3.0-or-later