Skip to main content
Glama
kimhjort

aria-mcp-affald-horsens

by kimhjort
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

aria-mcp-affald-horsens

A Model Context Protocol (MCP) server for household waste collection schedules in Horsens Kommune. Built for ARIA and shareable with the community.

Example output ARIA might give Kim:

i aften: rest/madaffald ud (tømmes mandag den 15. juni) næste papir/pap: tirsdag den 23. juni (om 10 dage)

Data Source

Data is fetched from PerfectWaste (https://europe-west3-perfect-waste.cloudfunctions.net), the backend powering Horsens Kommune's waste portal. The API is unofficial and undocumented — it was reverse-engineered from the portal and community Home Assistant integrations. There is no guarantee of stability; Horsens might migrate providers without notice.

The legacy horsens.renoweb.dk ASMX endpoint (GetAffaldsplanMateriel_mitAffald) is MitID-gated and cannot be used headlessly. Only address search on that endpoint is unauthenticated, but it is useless without schedule access. PerfectWaste is fully headless with no auth.

Best-effort only. Always verify collection dates at horsens.dk/affald.

Related MCP server: smhi-mcp

Install & Run

npx aria-mcp-affald-horsens

Or install globally:

npm install -g aria-mcp-affald-horsens
aria-mcp-affald-horsens

Requires Node.js 20 or later.

Tools

find_address

Search for a Horsens address and return PerfectWaste address candidates (id + display name).

Parameters:

Name

Type

Required

Description

query

string

Yes

Address string to search (e.g. "Vestergade 5", "Søndergade 1, 8700 Horsens")

Returns:

{
  "query": "Vestergade 5",
  "candidates": [
    { "addressID": "39429", "displayName": "Vestergade 5, 8732 Hovedgård" },
    { "addressID": "47864", "displayName": "Vestergade 5, 8700 Horsens" }
  ]
}

next_collection

Return the next upcoming collection date for each waste fraction at an address.

Parameters:

Name

Type

Required

Description

address

string

Yes

Free-text address or raw PerfectWaste addressID (digits only)

Returns:

{
  "addressID": "47864",
  "addressDisplay": "Vestergade 5, 8700 Horsens",
  "asOf": "2026-06-13T08:00",
  "nextByFraction": [
    {
      "fractionName": "Rest - Mad",
      "date": "2026-06-15T00:00:00.000Z",
      "dateLocal": "2026-06-15",
      "dateLabel": "mandag den 15. juni 2026",
      "daysUntil": 2,
      "putOutTonight": false
    },
    {
      "fractionName": "Papir, pap og tekstilaffald",
      "date": "2026-06-23T00:00:00.000Z",
      "dateLocal": "2026-06-23",
      "dateLabel": "tirsdag den 23. juni 2026",
      "daysUntil": 10,
      "putOutTonight": false
    },
    {
      "fractionName": "Plast og drikkekarton - Glas og metal",
      "date": "2026-06-26T00:00:00.000Z",
      "dateLocal": "2026-06-26",
      "dateLabel": "fredag den 26. juni 2026",
      "daysUntil": 13,
      "putOutTonight": false
    }
  ],
  "notice": "Data source: PerfectWaste (unofficial API, Horsens Kommune). ..."
}

putOutTonight is true when the collection is tomorrow — use it for reminders like "i aften: rest/madaffald ud".

collection_calendar

Return all upcoming collection events for the next N weeks.

Parameters:

Name

Type

Required

Description

address

string

Yes

Free-text address or raw PerfectWaste addressID

weeks

number

No

Look-ahead in weeks (default 4, max 52)

Returns: Same fields as next_collection events but as a flat chronological list covering the full window.

Environment Variables

Variable

Default

Description

RENOWEB_HOST

https://europe-west3-perfect-waste.cloudfunctions.net

Override the PerfectWaste base URL. Useful if another kommune uses the same backend at a different endpoint.

RENOWEB_MUNICIPALITY

615

Municipality code. 615 = Horsens. Other PerfectWaste kommuner may use different codes.

The RENOWEB_* names are intentional — they keep the interface familiar and forward-compatible if a true RenoWeb headless path is discovered later.

ARIA MCP Config

Add to your ARIA MCP config (mcpServers in ARIA credentials):

{
  "command": "npx",
  "args": ["-y", "aria-mcp-affald-horsens"],
  "env": {}
}

ARIA can then answer questions like:

  • "hvornår tømmes papir næste gang?"

  • "hvad skal ud i aften?"

  • "vis affaldskalender for de næste 4 uger på Vestergade 5"

Fragility Notes

  • API is undocumented. PerfectWaste has no published SLA for this endpoint. It has been stable since at least early 2026, but could break without notice.

  • Municipality codes. The 615 code for Horsens was discovered empirically. Other kommuner using PerfectWaste will have different codes.

  • Address coverage. Some commercial/institutional addresses (e.g. Rådhustorvet 4) return empty collection data — the portal apparently only covers residential collection routes.

  • Calendar depth. PerfectWaste typically returns ~3 months of data. The weeks parameter is capped client-side.

Development

git clone https://github.com/kimhjort/aria-mcp-affald-horsens
cd aria-mcp-affald-horsens
npm install
npm run build
npm test

License

MIT — see LICENSE.

Available Tools

3 tools
collection_calendarA

Return all upcoming waste collection events for a Horsens address over the next N weeks. Each event includes the date (ISO 8601), a human-readable Danish date label (e.g. "mandag den 15. juni 2026"), daysUntil, and the fractions to be collected. Use this when ARIA needs to plan ahead or answer "hvornår tømmes X de næste uger?". The 'address' parameter accepts a free-text address string or a raw PerfectWaste addressID. The 'weeks' parameter controls the look-ahead window (default 4, max 52).

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesHorsens address string (e.g. "Vestergade 5") or a PerfectWaste addressID (digits only).
weeksNoNumber of weeks to look ahead (default 4, max 52).

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes return fields (date, label, daysUntil, fractions) but does not disclose error handling, required permissions, or behavior on invalid addresses. Lacks details on side effects or rate limits, though tool is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two well-structured sentences: first states core function and return format, second gives usage guidance, third details parameters. No fluff, each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, parameters, and return format (important since no output schema). Missing details on authentication, error handling, or scope limitations beyond 'Horsens address'. Adequate for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions identical to the description. The description restates parameter meanings (address type, weeks range) without adding new semantic value beyond the schema, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns upcoming waste collection events for a Horsens address over N weeks, using specific verb 'return' and resource 'waste collection events'. It distinguishes from siblings find_address (address lookup) and next_collection (single next event) by emphasizing multi-week look-ahead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use this when ARIA needs to plan ahead or answer "hvornår tømmes X de næste uger?"' This directly guides the agent to choose this tool for planning multiple weeks rather than a single next collection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_addressA

Search for a Horsens Kommune address and return PerfectWaste address candidates (each with an addressID and a displayName). Use this to resolve a free-text address string before calling next_collection or collection_calendar, or to disambiguate when multiple addresses match (e.g. Søndergade 1 in both 8700 and 8740). Returns up to 30 candidates ordered by relevance.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesAddress string to search for in Horsens Kommune (e.g. "Vestergade 5", "Søndergade 1, 8700 Horsens").

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description discloses return format, limit of 30 candidates, and relevance ordering. Does not mention side effects or rate limits, but acceptable for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words; first sentence states purpose, second gives usage guidance and example. Very efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter search tool with no output schema and two siblings, the description covers input, output, limits, ordering, and usage context. Completely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with a description for the query parameter. The tool description adds context about search scope (Horsens Kommune) and disambiguation, enhancing meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for a Horsens Kommune address and returns candidates with addressID and displayName. It differentiates from siblings by specifying this tool resolves addresses before using next_collection or collection_calendar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use before next_collection or collection_calendar, and to disambiguate multiple matches. Provides an example. Could mention when not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

next_collectionA

Return the next upcoming waste collection date for each fraction at a given Horsens address. Fractions include Rest - Mad (general/food waste), Papir, pap og tekstilaffald (paper/cardboard/textiles), and Plast og drikkekarton - Glas og metal (plastic/cartons/glass/metal). The 'putOutTonight' flag is true when that fraction is collected tomorrow — use it to remind Kim "i aften: [fraktion] ud". The 'address' parameter accepts a free-text address string or a raw PerfectWaste addressID (digits only). When the address is ambiguous, prefers 8700 Horsens results.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesHorsens address string (e.g. "Vestergade 5") or a PerfectWaste addressID (digits only). Ambiguous queries prefer 8700 Horsens.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It explains the 'putOutTonight' flag and its use for reminders, and clarifies address handling (free text or ID, ambiguity resolution). No destructive behavior is described, which is appropriate for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, covering key information in a few sentences without unnecessary verbosity. It could be improved with bullet points, but remains clear and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one parameter, no output schema), the description is sufficiently complete. It explains the return value (next collection date per fraction, with flag), address format, and ambiguity handling. No major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but the description adds value by explaining that 'address' can be a free-text string or a PerfectWaste addressID, and that ambiguous queries prefer 8700 Horsens. This goes beyond the schema's basic type description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Return the next upcoming waste collection date for each fraction at a given Horsens address.' It lists specific fractions and the 'putOutTonight' flag, clearly differentiating from sibling tools like 'collection_calendar' and 'find_address'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions that ambiguous queries prefer 8700 Horsens, but does not explicitly state when to use this tool over siblings like 'collection_calendar' or 'find_address'. The usage context is implied but not directly compared.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcollection_calendar
    • First observedfind_address
    • First observednext_collection
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: address resolution, next collection, and calendar of upcoming collections. No overlap.

Naming Consistency5/5

All tool names use consistent snake_case verb_noun pattern: find_address, next_collection, collection_calendar.

Tool Count5/5

Three tools are well-scoped for the domain of waste collection lookup in a single municipality—sufficient without being excessive.

Completeness5/5

The set covers address disambiguation, immediate next collection, and future planning via calendar. No obvious gaps.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-dawa

    itk-dev
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for the Danish Address Web API (DAWA), enabling free-text address search, house number search, and detailed address lookup by ID.
    -

  • smhi-mcp

    hniska
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that provides real-time weather data, forecasts, and historical weather information from SMHI (Swedish Meteorological and Hydrological Institute) for any location in Sweden.
    2
    -

  • elpriser-mcp

    x2q
    A
    license
    A
    quality
    D
    maintenance
    MCP server for Danish electricity prices, providing current spot price, cheapest hours, and 7-day forecast for DK1 and DK2 areas.
    5
    6 npm
    MIT