Abfallkalender Deutschland

io.github.AlpayCv0.2.0Updated Sep 28, 2026

Waste collection dates for German addresses from municipal authority calendars.

VerifiedStreamable HTTPWeb executableOther

Installation

In SourceWeft

  1. Open Abfallkalender Deutschland in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "abfall-mcp-server": {
      "type": "http",
      "url": "https://abfall-mcp.alpaycelik.dev/mcp"
    }
  }
}

README

abfall-mcp-server

English · Deutsch

[CI] [License: MIT] [Python 3.11+] [Providers: 995]

[MCP 2026-07-28 readiness]

MCP server for the waste collection calendars of German cities and districts. Looks up collection dates — residual waste, organic waste, paper, packaging, bulky waste, hazardous waste collection points — for a given address.

Website and interactive setup guide: abfall-mcp.alpaycelik.dev.

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

Why this is not trivial

Waste management in Germany is organised municipally. There is no nationwide API — roughly 400 public waste authorities each run their own portal, backed by a handful of software platforms (Abfall.IO/AbfallPlus, AbfallNavi, Jumomind, AWIDO, C-Trace, Müllmax, plus many plain ICS exports).

This server uses mampfes/hacs_waste_collection_schedule (MIT) as its data source — an actively maintained project with over 950 source modules. Its inner package is independent of Home Assistant and is wired in here as a Git submodule.

The actual work of this project is turning an address into the responsible waste authority and its internal parameters. In Home Assistant a human clicks that together once; an MCP server has to do it on its own.

Installation

The server runs from a repository checkout, not as an installed package: it needs the data source under vendor/ and the registry under data/, both resolved relative to the project root. That is also why it is not on PyPI — a wheel would install cleanly and still not work.

bash
git clone --recurse-submodules https://github.com/AlpayC/abfall-mcp-server.gitcd abfall-mcp-serveruv syncuv run pytest

data/providers.json is checked in, so the server starts right away. After a submodule update, rebuild it:

bash
uv run python scripts/build_registry.py

Wiring it up

Public remote via Streamable HTTP:

json
{  "mcpServers": {    "abfall": {      "url": "https://abfall-mcp.alpaycelik.dev/mcp"    }  }}

The service health endpoint is https://abfall-mcp.alpaycelik.dev/health.

Locally over stdio — in claude_desktop_config.json or .mcp.json:

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

As an HTTP service:

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

Keep in mind that every HTTP request puts load on the authorities' portals and on Nominatim. For anything beyond personal use, put a cache in front and your own Nominatim instance behind it (ABFALL_MCP_NOMINATIM_URL).

Tools

Tool names and responses are German, because the domain and the users are.

ToolPurpose
abfuhrtermineAddress in, collection dates out. The usual entry point.
finde_traegerSearch authorities by place or company name, no geocoding.
traeger_detailsWhich arguments does an authority expect?
abfuhrtermine_fuer_traegerTargeted query, e.g. to answer a follow-up question.
abdeckungHow many authorities and data sources are covered.

Plus the resource abfall://traeger with the full list of authorities.

Asking beats guessing

When a value cannot be determined unambiguously, the server returns status: "rueckfrage" along with the concrete list of options instead of guessing. That is deliberate: a wrongly guessed town cheerfully returns the neighbouring municipality's calendar — a wrong answer that looks like a right one.

Coverage, measured

scripts/build_registry.py collects 995 waste authorities from 150 source modules.

scripts/smoke.py queries real addresses against the real portals. A run over 21 addresses across Germany (as of Aug 2026):

OutcomeShare
Collection dates returned directly48 %
Follow-up question for a missing detail14 %
No authority returned dates38 %

That is the measured number, not an estimate — and the reason to state it here: "covers every German city" is true of the authority list, not of fully automatic resolution from a bare address.

Authorities with their own ID lookup

Some portals require internal identifiers that cannot be derived from an address. For these, the portal's address dialog is reimplemented in lookup.py:

AuthorityIdentifierScope
Abfall.IO / AbfallPlusf_id_kommune, f_id_strasse, …41 authorities
Stadtreinigung HamburghnIdHamburg
Berliner Stadtreinigungsbetriebeschedule_idBerlin

The upstream wizard for Hamburg is stale by now — the portal moved its form to a JavaScript component, whose address endpoint is read out of the page here.

Where the remaining cases fail

  • Further ID arguments with no lookup path: standort in Dresden, idHouseNumber in Leipzig, streetnr in Stuttgart. One more resolver each, following the same pattern as the three above.
  • Portals using different spellings that ship no list of suggestions (Erfurt, Kiel).
  • Outages, rate limiting and malformed responses on the authorities' side (Saarbrücken returns HTML instead of ICS).

Layout

FileResponsibility
wcs.pyBridge to the vendored library; registers the package deliberately instead of putting it on sys.path (its parent directory holds a calendar.py that shadows the stdlib).
registry.pyAuthority list and location search with German stemming.
geo.pyNominatim, address variants, plausibility checks.
resolve.pyAddress → authority → resolved arguments → collection dates.
lookup.pyAddress dialogs for authorities with internal IDs (Abfall.IO, Hamburg, BSR).
server.pyMCP tools, stdio and HTTP.

The registry is not built at runtime: data/providers.json is produced by a script so that starting the server does not import 150 modules. Rebuild it after a submodule update.

Data sources and usage

Collection dates come from the portals of the respective waste authorities, address resolution from Nominatim (OpenStreetMap). Nominatim has a usage policy — at most one request per second; the server honours it and caches results in ~/.cache/abfall-mcp-server/.

For dates something depends on (bulky waste, hazardous waste collection), it is worth checking the portal address that every response carries.

Contributing

The most useful contribution is a report that some authority does not work — there is an issue template with the right questions. How to add an authority resolver is in CONTRIBUTING.md; security issues belong in a private report, see SECURITY.md. Changes are listed in the CHANGELOG. Agents working on this repository should read AGENTS.md.

One principle runs through the whole project and applies to contributions too: when in doubt, ask — do not guess. A wrongly guessed town cheerfully returns the neighbouring municipality's calendar — a wrong answer that looks like a right one.

License

MIT, see LICENSE. The submodule vendor/hacs_waste_collection_schedule is under its own MIT license, Copyright (c) 2020 Steffen Zimmermann — this repository only references it, it does not ship the code. Third-party attributions are collected in NOTICE.

Source: README.md at commit 10bdac5

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.0LatestSep 16, 2026