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。

claude_desktop_config.json または .mcp.json を使い、stdio でローカル接続する場合：

{
  "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が該当します。上記 3 件と同じパターンに沿ったリゾルバーをそれぞれ 1 つ追加する必要があります。
• 候補リストを提供せず、異なる綴りを使うポータル（エアフルト、キール）。
• 当局側の停止、レート制限、形式不正のレスポンス（ザールブリュッケンは ICS の代わりに HTML を返します）。

構成

ファイル	役割
wcs.py	ベンダー提供ライブラリへのブリッジです。親ディレクトリに標準ライブラリのcalendar.pyをシャドーイングするファイルがあるため、sys.pathに追加するのではなく、意図的にパッケージを登録します。
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 には利用ポリシーがあり、リクエストは 1 秒あたり最大 1 回です。サーバーはこの制限を守り、結果を~/.cache/abfall-mcp-server/にキャッシュします。

粗大ごみや有害廃棄物の収集など、日付が重要なものについては、各レスポンスに含まれるポータルの住所を確認することをおすすめします。

コントリビューション

最も役立つのは、機能していない当局についての報告です。適切な質問が記載されたイシューテンプレートがあります。当局リゾルバーの追加方法についてはCONTRIBUTING.mdをご覧ください。セキュリティ上の問題は非公開で報告してください。詳細はSECURITY.mdをご覧ください。変更内容はCHANGELOGに記載されています。このリポジトリで作業するエージェントは、AGENTS.mdを読む必要があります。

プロジェクト全体に通じる原則があり、コントリビューションにも当てはまります。迷ったら、推測せずに尋ねてください。 誤って推測した町を指定すると、隣接する自治体のカレンダーが何食わぬ顔で返されます。正解に見える誤った回答です。

ライセンス

MIT です。詳細はLICENSEをご覧ください。サブモジュールvendor/hacs_waste_collection_scheduleは独自の MIT ライセンスの下で提供され、Copyright (c) 2020 Steffen Zimmermann が保有しています。このリポジトリは参照しているだけで、コードを同梱していません。サードパーティの帰属表示はNOTICEにまとめられています。