io.github.mohammad-abbasi-sh/feiertage-mcp
# 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
Scored across 6 tools
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.
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.
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.
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.