mcp-abfall

Englisch · Deutsch

MCP-Server für die Abfallkalender deutscher Städte und Landkreise. Ermittelt Abfuhrtermine — Restmüll, Biomüll, Papier, Verpackung, Sperrmüll, Schadstoffsammelstellen — für eine gegebene Adresse.

address ──▶ Nominatim ──▶ municipality + district ──▶ provider search (995)
                                                              │
                       collection dates ◀── portal ◀── resolve arguments

Warum das nicht trivial ist

Die Abfallentsorgung in Deutschland ist kommunal organisiert. Es gibt keine bundesweite API — rund 400 öffentliche Abfallbehörden betreiben jeweils ein eigenes Portal, dahinter stehen einige wenige Software-Plattformen (Abfall.IO/AbfallPlus, AbfallNavi, Jumomind, AWIDO, C-Trace, Müllmax, dazu viele einfache ICS-Exporte).

Dieser Server nutzt mampfes/hacs_waste_collection_schedule (MIT) als Datenquelle — ein aktiv gepflegtes Projekt mit über 950 Quellenmodulen. Sein enthaltenes Paket ist unabhängig von Home Assistant und wird hier als Git-Submodul eingebunden.

Die eigentliche Arbeit dieses Projekts besteht darin, eine Adresse in die zuständige Abfallbehörde und deren interne Parameter zu überführen. In Home Assistant klickt ein Mensch das einmal zusammen; ein MCP-Server muss das selbstständig erledigen.

Related MCP server: vnbdigital-mcp

Installation

Der Server läuft aus einem Repository-Checkout, nicht als installiertes Paket: Er benötigt die Datenquelle unter vendor/ und das Register unter data/, beide relativ zur Projektwurzel aufgelöst. Genau deshalb ist er auch nicht auf PyPI — ein Wheel würde sauber installieren und trotzdem nicht funktionieren.

git clone --recurse-submodules https://github.com/AlpayC/mcp-abfall.git
cd mcp-abfall
uv sync
uv run pytest

data/providers.json ist eingecheckt, sodass der Server sofort startet. Nach einem Submodul-Update erstelle es neu:

uv run python scripts/build_registry.py

Einbinden

Lokal über stdio — in claude_desktop_config.json oder .mcp.json:

{
  "mcpServers": {
    "abfall": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-abfall", "run", "mcp-abfall"]
    }
  }
}

Als HTTP-Dienst:

uv run mcp-abfall --http --host 127.0.0.1 --port 8000

Beachte, dass jede HTTP-Anfrage die Portale der Behörden und Nominatim belastet. Für alles über den persönlichen Gebrauch hinaus setze einen Cache davor und deine eigene Nominatim-Instanz dahinter (MCP_ABFALL_NOMINATIM_URL).

Tools

Toolnamen und Antworten sind auf Deutsch, weil die Domäne und die Nutzer es sind.

Außerdem die Ressource abfall://traeger mit der vollständigen Liste der Behörden.

Fragen statt Raten

Wenn ein Wert nicht eindeutig bestimmt werden kann, gibt der Server status: "rueckfrage" zusammen mit der konkreten Optionsliste zurück, statt zu raten. Das ist beabsichtigt: Eine falsch geratene Stadt liefert dann fröhlich den Kalender der Nachbargemeinde — eine falsche Antwort, die wie eine richtige aussieht.

Abdeckung, gemessen

scripts/build_registry.py erfasst 995 Abfallbehörden aus 150 Quellenmodulen.

scripts/smoke.py fragt reale Adressen gegen die echten Portale ab. Ein Lauf über 21 Adressen in ganz Deutschland (Stand: Aug. 2026):

Das ist die gemessene Zahl, keine Schätzung — und der Grund, sie hier zu nennen: „deckt jede deutsche Stadt ab“ trifft auf die Behördenliste zu, nicht auf die vollautomatische Auflösung aus einer bloßen Adresse.

Behörden mit eigener ID-Suche

Einige Portale verlangen interne Kennungen, die nicht aus einer Adresse abgeleitet werden können. Für diese wird der Adressdialog des Portals in lookup.py reimplementiert:

Der Upstream-Assistent für Hamburg ist inzwischen veraltet — das Portal hat sein Formular auf eine JavaScript-Komponente umgestellt, deren Adress-Endpunkt hier aus der Seite ausgelesen wird.

Wo die übrigen Fälle scheitern

• Weitere ID-Argumente ohne Lookup-Pfad: standort in Dresden, idHouseNumber in Leipzig, streetnr in Stuttgart. Für jedes dieser Argumente fehlt ein Resolver, der demselben Muster wie die drei obigen folgt.

• Portale mit abweichenden Schreibweisen, die keine Vorschlagsliste mitliefern (Erfurt, Kiel).

• Ausfälle, Rate-Limiting und fehlerhafte Antworten auf Seiten der Behörden (Saarbrücken liefert HTML statt ICS).

Aufbau

Das Register wird nicht zur Laufzeit erstellt: data/providers.json wird von einem Skript erzeugt, sodass der Serverstart keine 150 Module importiert. Erstelle es nach einem Submodul-Update neu.

Datenquellen und Nutzung

Die Abfuhrtermine stammen aus den Portalen der jeweiligen Abfallbehörden, die Adressauflösung von Nominatim (OpenStreetMap). Nominatim hat eine Nutzungsrichtlinie — höchstens eine Anfrage pro Sekunde; der Server hält sich daran und cached Ergebnisse in ~/.cache/mcp-abfall/.

Bei Terminen, von denen etwas abhängt (Sperrmüll, Schadstoffsammlung), lohnt es sich, die Portaladresse zu prüfen, die jede Antwort mitliefert.

Mitwirken

Der nützlichste Beitrag ist ein Bericht, dass eine Behörde nicht funktioniert — dafür gibt es eine Issue-Vorlage mit den richtigen Fragen. Wie man einen Behörden-Resolver hinzufügt, steht in CONTRIBUTING.md; Sicherheitsprobleme gehören in einen privaten Bericht, siehe SECURITY.md. Änderungen sind im CHANGELOG aufgeführt. Agents, die an diesem Repository arbeiten, sollten AGENTS.md lesen.

Ein Prinzip zieht sich durch das gesamte Projekt und gilt auch für Beiträge: Im Zweifel nachfragen — nicht raten. Eine falsch geratene Stadt liefert fröhlich den Kalender der Nachbargemeinde — eine falsche Antwort, die wie eine richtige aussieht.

Lizenz

MIT, siehe LICENSE. Das Submodul vendor/hacs_waste_collection_schedule steht unter seiner eigenen MIT-Lizenz, Copyright (c) 2020 Steffen Zimmermann — dieses Repository verweist nur darauf, es liefert den Code nicht aus. Zuschreibungen an Dritte sind in NOTICE gesammelt.