Abfallkalender Deutschland

abfall-mcp-server

英语 · 德语

用于查询德国城市和区县垃圾收集日历的 MCP 服务。 可根据给定地址查询收集日期——包括其他垃圾、有机垃圾、纸张、包装物、大件垃圾、有害垃圾收集点。

网站和交互式设置指南： abfall-mcp.alpaycelik.dev。

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

为什么这并非易事

德国的垃圾管理由各市镇负责。没有全国统一的 API——大约 400 个公共垃圾管理机构各自运营门户，背后依托少数几种软件平台（Abfall.IO/AbfallPlus、AbfallNavi、Jumomind、AWIDO、C-Trace、Müllmax，以及许多普通 ICS 导出文件）。

本服务使用 mampfes/hacs_waste_collection_schedule （MIT）作为数据源——这是一个积极维护的项目，包含 950 多个数据源模块。其内部包独立于 Home Assistant，并作为 Git 子模块接入此项目。

此项目真正要做的，是将一个地址转换为负责的垃圾管理机构及其内部参数。在 Home Assistant 中，用户只需手动点击一次即可完成；而 MCP 服务必须自行完成这项工作。

安装

此服务从仓库检出目录运行，而不是作为已安装的软件包运行：它需要 vendor/ 下的数据源和 data/ 下的注册表，二者都相对于项目根目录解析。这也是它没有发布到 PyPI 的原因——wheel 虽然可以顺利安装，却仍然无法运行。

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

data/providers.json 已提交到仓库，因此服务可以立即启动。更新子模块后，请重新构建：

uv run python scripts/build_registry.py

接入

通过 Streamable HTTP 使用公共远程服务：

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

服务健康检查端点为 https://abfall-mcp.alpaycelik.dev/health。

通过 stdio 在本地运行——配置在 claude_desktop_config.json 或 .mcp.json 中：

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

作为 HTTP 服务运行：

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

请注意，每个 HTTP 请求都会给各管理机构的门户和 Nominatim 增加负载。若用于个人用途之外的场景，请在前面加上缓存，并在后端部署自己的 Nominatim 实例（ABFALL_MCP_NOMINATIM_URL）。

工具

工具名称和响应均为德语，因为该领域及其用户使用德语。

工具	用途
abfuhrtermine	输入地址，获取收集日期。通常的入口。
finde_traeger	按地点或公司名称搜索管理机构，不进行地理编码。
traeger_details	查询管理机构需要哪些参数。
abfuhrtermine_fuer_traeger	定向查询，例如用于回答后续问题。
abdeckung	查询覆盖的管理机构和数据源数量。

此外还提供资源 abfall://traeger，其中包含完整的管理机构列表。

询问胜过猜测

如果无法明确确定某个值，服务会返回 status: "rueckfrage"，并附上具体选项列表，而不是进行猜测。这是有意为之：猜错城镇时，服务会毫无察觉地返回邻近市镇的日历——这样的错误答案看起来却像是正确答案。

覆盖情况，实测数据

scripts/build_registry.py 从 150 个源模块中收集了 995 个废弃物管理机构。

scripts/smoke.py 使用真实地址查询真实门户。截至 2026 年 8 月，对德国 21 个地址进行的一次运行结果如下：

结果	占比
直接返回收集日期	48 %
需要补充缺失信息	14 %
没有机构返回日期	38 %

这是实测数据，不是估算——在此说明的原因是：“覆盖德国所有城市”指的是机构列表，而不是仅凭地址即可完全自动解析。

有独立 ID 查询功能的机构

部分门户需要无法根据地址推导的内部标识符。对于这些门户，lookup.py 重新实现了门户的地址对话框：

机构	标识符	范围
Abfall.IO / AbfallPlus	f_id_kommune、f_id_strasse、…	41 个机构
Stadtreinigung Hamburg	hnId	汉堡
Berliner Stadtreinigungsbetriebe	schedule_id	柏林

汉堡的上游向导现在已经过时——门户将表单迁移到了 JavaScript 组件，这里会从页面读取其地址端点。

其余情况为何失败

• 缺少查询路径的其他 ID 参数：德累斯顿的 standort、莱比锡的 idHouseNumber、斯图加特的 streetnr。每种情况都需要再实现一个解析器，遵循以上三个解析器的相同模式。
• 使用不同拼写且不提供建议列表的门户（埃尔福特、基尔）。
• 机构端的服务中断、速率限制和格式错误的响应（萨尔布吕肯返回的是 HTML，而不是 ICS）。

目录结构

文件	职责
wcs.py	对接 vendored 库；有意注册该包，而不是将其放入 sys.path（其父目录中有一个 calendar.py，会遮蔽标准库）。
registry.py	机构列表和采用德语词干提取的地点搜索。
geo.py	Nominatim、地址变体和合理性检查。
resolve.py	地址 → 机构 → 解析后的参数 → 收集日期。
lookup.py	有内部 ID 的机构的地址对话框（Abfall.IO、汉堡、BSR）。
server.py	MCP 工具、stdio 和 HTTP。

运行时不会构建注册表：data/providers.json 由脚本生成，这样启动服务时就不必导入 150 个模块。更新子模块后请重新构建。

数据来源和使用

收集日期来自相应废弃物管理机构的门户，地址解析则来自 Nominatim（OpenStreetMap）。Nominatim 有使用政策——每秒最多请求一次；本服务遵守该政策，并将结果缓存到 ~/.cache/abfall-mcp-server/。

对于需要依赖收集日期的事项（大件垃圾、有害废弃物收集），建议查看每个响应中附带的门户地址。

贡献

最有帮助的贡献是报告某个机构无法正常工作——我们提供了一个问题模板，其中列有需要提供的信息。如何添加机构解析器，请参阅CONTRIBUTING.md；安全问题请通过私密报告提交，参见SECURITY.md。变更记录见CHANGELOG。在此代码库中工作的 Agent 应阅读 AGENTS.md。

整个项目始终遵循一个原则，贡献也不例外：有疑问时就提问，不要猜测。 猜错城镇时，系统会欣然返回邻近市镇的日历——错误答案看起来却像是正确答案。

许可证

MIT，参见 LICENSE。子模块 vendor/hacs_waste_collection_schedule 使用其自身的 MIT 许可证， Copyright (c) 2020 Steffen Zimmermann——本代码库仅引用该子模块，并不包含其中的代码。第三方归属信息汇总在 NOTICE。