Skip to main content
Glama
io.github.mohammad-abbasi-sh/feiertage-mcp

io.github.mohammad-abbasi-sh/feiertage-mcp

README.md
# feiertage-mcp ๐Ÿ“…

mcp-name: io.github.mohammad-abbasi-sh/feiertage-mcp

Unofficial **read-only** MCP server for **German public holidays** (gesetzliche Feiertage) via the [feiertage-api.de API](https://feiertage-api.de) (bundesAPI project): holidays per year and federal state, is-it-a-holiday checks, the next holiday from a date, and holidays in a date range. No key, no login.

> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with feiertage-api.de / the bundesAPI project.

## For AI agents

Add to your MCP client config (stdio):

```json
{
  "mcpServers": {
    "feiertage": {
      "command": "uvx",
      "args": ["feiertage-mcp==0.1.0"]
    }
  }
}
```

Or run locally: `python -m feiertage_mcp.server` (needs `mcp<2`, `httpx`).

## Tools

| Tool | Description |
|------|-------------|
| `feiertage_list_holidays` | Public holidays of one year in one federal state (optional month filter) |
| `feiertage_is_holiday` | Is a date (YYYY-MM-DD) a public holiday in one state? |
| `feiertage_next_holiday` | The next public holiday on or after a date (looks into the next year) |
| `feiertage_holidays_between` | Public holidays in a date range (max ~2 years) |
| `feiertage_list_states` | All 16 federal states + NATIONAL (nationwide holidays) |
| `feiertage_health` | Reachability check (ok / blocked / error) โ€” one polite request |

Example output (`feiertage_is_holiday` / 2026-10-03, NATIONAL):

```json
{"date": "2026-10-03", "weekday": "Saturday", "weekday_de": "Samstag",
 "state": "NATIONAL", "is_holiday": true,
 "holidays": ["Tag der Deutschen Einheit"],
 "details": [{"name": "Tag der Deutschen Einheit", "date": "2026-10-03",
   "note": null, "note_only": false, "weekday": "Saturday",
   "weekday_de": "Samstag"}]}
```

Notes:
- State codes are the 2-letter codes: BW, BY, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH โ€” or `NATIONAL` for the nationwide holidays (Neujahrstag, Karfreitag, Ostermontag, Tag der Arbeit, Christi Himmelfahrt, Pfingstmontag, Tag der Deutschen Einheit, 1./2. Weihnachtstag). Use `feiertage_list_states` for the full list.
- Holiday names are German; each dated holiday also carries its weekday in English and German.
- A few entries have no date (`note_only: true`) โ€” they are notes, e.g. school-free days, not statutory public holidays. Date-based tools skip them.
- Years 1900โ€“2100 are accepted; the API serves historical and future calendars.
- `feiertage_holidays_between` fetches one request per year in the range (max ~2 years).

Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) โ€” [Almanibama](https://almanibama.ir) ยท [mabbasi.ir](https://mabbasi.ir)

TDQS

A4/5.0

Scored across 6 tools

Disambiguation4/5

Each tool has a clearly distinct query shape: year/month listing, single-date check, next-holiday lookup, date-range scan, state code reference, and health probe. The only mild overlap is between feiertage_list_holidays with a month filter and feiertage_holidays_between, which can return similar data, but the descriptions make the intended use of each clear.

Naming Consistency5/5

All six tools use the same feiertage_ prefix followed by a consistent verb_noun snake_case pattern (list_holidays, is_holiday, next_holiday, holidays_between, list_states, health). The convention is predictable and readable throughout.

Tool Count5/5

Six tools is a well-scoped set for a read-only holiday lookup service; every tool maps to a distinct query need (listing, checking, upcoming, range, state codes, availability). No filler or redundant endpoints.

Completeness4/5

The surface covers the full read-only lifecycle: discovering valid state codes, listing holidays, checking a date, finding the next one, scanning ranges, and probing API health. Minor gap: no tool to resolve a holiday name back to dates or to return holiday metadata beyond name/date, but agents can work around this via the listing tools.