mcp-abfall

英文 · 德语

适用于德国城市和地区的垃圾清运日历的 MCP 服务器。 根据给定地址查询清运日期——剩余垃圾、有机垃圾、废纸、包装垃圾、 大件垃圾、有害垃圾收集点。

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 服务器必须自己完成。

Related MCP server: vnbdigital-mcp

安装

服务器从仓库检出目录运行，而不是作为已安装的包：它需要 vendor/ 下的数据源和 data/ 下的注册表，两者都相对于项目根目录解析。这也是它不在 PyPI 上的原因——wheel 包可以正常安装，但仍然无法工作。

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

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

uv run python scripts/build_registry.py

接入方式

通过 stdio 在本地使用——在 claude_desktop_config.json 或 .mcp.json 中：

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

作为 HTTP 服务：

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

请记住，每个 HTTP 请求都会给各机构的门户和 Nominatim 带来负载。对于超出个人使用的场景，请在前面放置缓存，并在其后使用你自己的 Nominatim 实例（MCP_ABFALL_NOMINATIM_URL）。

工具

工具名称和响应均为德语，因为该领域和用户都是德语的。

另外还有 abfall://traeger 资源，包含完整的机构列表。

询问胜过猜测

当某个值无法明确确定时，服务器会返回 status: "rueckfrage" 以及具体的选项列表，而不是猜测。这是有意为之：猜错城镇会愉快地返回邻近市镇的日历——一个看起来像正确回答的错误答案。

覆盖率，实测

scripts/build_registry.py 从 150 个源模块收集了 995 个垃圾处理机构。

scripts/smoke.py 用真实地址查询真实门户。一次覆盖德国 21 个地址的运行（截至 2026 年 8 月）：

这是实测数字，不是估计——也是在此说明的原因：“覆盖德国每一个城市”只对机构列表成立，而不是对仅凭一个地址的全自动解析成立。

拥有独立 ID 查询的机构

一些门户需要无法从地址推导出的内部标识符。对于这些门户，地址对话框已在 lookup.py 中重新实现：

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

剩余情况为何失败

• 更多 ID 参数没有查询路径：德累斯顿的 standort、莱比锡的 idHouseNumber、斯图加特的 streetnr。每个都需要再添加一个解析器，按照上述三个相同的模式。

• 使用不同拼写的门户，且不提供建议列表（埃尔福特、基尔）。

• 机构侧的中断、速率限制和格式错误的响应（萨尔布吕肯返回 HTML 而不是 ICS）。

布局

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

数据来源与使用

清运日期来自各垃圾处理机构的门户，地址解析来自 Nominatim（OpenStreetMap）。Nominatim 有使用政策——每秒最多一个请求；服务器遵守该政策，并将结果缓存在 ~/.cache/mcp-abfall/ 中。

对于某些事项所依赖的日期（大件垃圾、有害垃圾收集），值得核对每个响应携带的门户地址。

贡献

最有用的贡献是报告某个机构无法工作——有一个 问题模板 包含了正确的问题。如何添加机构解析器见 CONTRIBUTING.md；安全问题应通过私下报告，参见 SECURITY.md。变更列在 CHANGELOG 中。在此仓库上工作的智能体应阅读 AGENTS.md。

一条原则贯穿整个项目，也适用于贡献：有疑问时，询问——不要猜测。 猜错城镇会愉快地返回邻近市镇的日历——一个看起来像正确回答的错误答案。

许可证

MIT，参见 LICENSE。子模块 vendor/hacs_waste_collection_schedule 使用其自身的 MIT 许可证，版权所有 (c) 2020 Steffen Zimmermann——本仓库仅引用它，不附带其代码。第三方署名信息收集在 NOTICE 中。