# Tankerkönig MCP — Live German Fuel Prices for AI Assistants

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io/)

An [MCP](https://modelcontextprotocol.io/) server that gives Claude, Cursor, or any
MCP-compatible AI assistant access to **real-time fuel prices at 14,000+ gas stations
in Germany**.

The data is official: German law requires every filling station to report price changes
in real time to the *Markttransparenzstelle für Kraftstoffe* (MTS-K) at the Federal Cartel
Office. [Tankerkönig](https://creativecommons.tankerkoenig.de) redistributes that feed
free of charge under CC BY 4.0.

> **Deutsch:** MCP-Server für aktuelle Benzin- und Spritpreise in Deutschland.
> Findet die günstigste Tankstelle (E5, E10, Diesel) in deiner Nähe — direkt im KI-Chat.

## What you can ask

Once connected, just talk to your assistant normally:

- *"Where's the cheapest E10 near Munich right now?"*
- *"Show me diesel prices within 10 km of Hamburg Hauptbahnhof."*
- *"I'm driving Stuttgart → Nuremberg tomorrow. Where should I fill up?"*
- *"Wo tanke ich gerade am günstigsten in Köln?"*

Example response:

```
DIESEL prices, cheapest first:
• 2.209 € — Sprint, Residenzstr. Berlin (4.9 km)
• 2.219 € — Shell, Prinzenallee Berlin (4.3 km)
• 2.269 € — TotalEnergies, Chausseestr. Berlin (2.6 km)

Data: tankerkoenig.de (MTS-K, CC BY 4.0)
```

## Tools

| Tool | Arguments | What it does |
|---|---|---|
| `find_fuel` | `location`, `fuel_type` (e5/e10/diesel), `radius_km` (1–25) | Cheapest stations near a place name or address |
| `find_fuel_at` | `lat`, `lng`, `fuel_type`, `radius_km` | Same, by exact GPS coordinates |

Only **open** stations with a current price are returned, sorted cheapest first.
Place names are resolved via [OpenStreetMap Nominatim](https://nominatim.openstreetmap.org/).

## Setup

### 1. Get a free API key (2 minutes + approval wait)

Tankerkönig issues a personal key to every user — this is required by their terms, so
the server cannot ship with a shared one.

1. Go to **[creativecommons.tankerkoenig.de](https://creativecommons.tankerkoenig.de)**
2. Fill in the form (name, email, purpose — "personal / hobby project" is fine)
3. Confirm the email you receive
4. The key arrives by email. Approval is manual, so it can take anywhere from a few
   minutes to a couple of days.

The key is free and has no usage cost.

### 2a. Hosted (easiest)

Available on the [MCPize marketplace](https://mcpize.com/mcp/tankerkoenig-mcp):

```bash
mcpize install tankerkoenig-mcp
```

You'll be prompted for your Tankerkönig key; it is stored per-user and never shared.

### 2b. Local install

```bash
git clone https://github.com/fluxionlabsai-ops/tankerkoenig-mcp.git
cd tankerkoenig-mcp
python3 -m venv .venv
.venv/bin/pip install .
```

Then add it to your MCP client. For **Claude Desktop**, edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tankerkoenig": {
      "command": "/absolute/path/to/tankerkoenig-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/tankerkoenig-mcp/server.py"],
      "env": { "TANKERKOENIG_API_KEY": "your-key-here" }
    }
  }
}
```

For **Claude Code**:

```bash
claude mcp add tankerkoenig \
  -e TANKERKOENIG_API_KEY=your-key-here \
  -- /absolute/path/to/tankerkoenig-mcp/.venv/bin/python \
     /absolute/path/to/tankerkoenig-mcp/server.py
```

Restart your client, and ask it about fuel prices.

## Security notes

The API key is read **only** from the `TANKERKOENIG_API_KEY` environment variable —
never from a file in the repo, and never hard-coded.

Tankerkönig passes the key as a URL query parameter, which HTTP client libraries happily
log at INFO level. This server explicitly silences the `httpx` logger in both the entry
point and the core module, and strips the request URL out of upstream HTTP errors before
they surface. Both behaviours are covered by regression tests
(`test_http_error_does_not_leak_key`, `test_httpx_logger_muted_on_plain_import`).

## Tests

```bash
.venv/bin/python -m unittest test_tankerkoenig -v
```

## Attribution & licence

- **Code:** MIT — see [LICENSE](LICENSE).
- **Data:** © [Tankerkönig](https://creativecommons.tankerkoenig.de), sourced from
  Markttransparenzstelle für Kraftstoffe, licensed
  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Every response from this
  server carries that attribution — please keep it if you build on this.
- **Geocoding:** © OpenStreetMap contributors, ODbL.

Not affiliated with Tankerkönig, MTS-K, or the Bundeskartellamt.

---

<sub>Keywords: German fuel prices MCP · Benzinpreise · Spritpreise · Dieselpreis ·
Tankstellen Deutschland · MTS-K API · Tankerkönig API · cheapest gas station Germany ·
Claude MCP server · Model Context Protocol</sub>