# feiertage-mcp: Deutsche Feiertage + Schulferien MCP

[![CI](https://github.com/drilongit/feiertage-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/drilongit/feiertage-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](LICENSE)
[![Data: ODbL](https://img.shields.io/badge/school%20data-ODbL--1.0-green.svg)](DATA_LICENSE.md)

An [MCP](https://modelcontextprotocol.io) server that answers **German public holidays per Bundesland**
and **school holidays (Schulferien)** for Claude, Cursor, Codex and any other MCP client.
Offline, read-only, no API key and no network calls at runtime.

[Deutsch weiter unten](#deutsch)

## Why

LLMs often get German holidays wrong: Fronleichnam is not nationwide, Reformationstag became a holiday
in the north only in 2018, Berlin added Frauentag in 2019, Mecklenburg-Vorpommern in 2023, and
Mariä Himmelfahrt in Bayern applies only in some municipalities. This server computes them from the
holiday laws and returns exact, sourced answers. It is useful for scheduling, delivery dates,
Handwerk planning, payroll and travel.

## Tools

| Tool | What it does |
|---|---|
| `list_states` | The 16 Bundesländer with codes (`NW`, `BY`, ...) |
| `get_public_holidays` | Statutory holidays for a year and state (optionally partial/local ones) |
| `holiday_overview` | Every holiday of a year with the states where it applies |
| `is_public_holiday` | Is this date a holiday in this state? |
| `next_public_holidays` | The next N holidays from a date |
| `count_working_days` | Working days between two dates, without weekends and holidays (optional Saturday) |
| `get_school_holidays` | School-holiday periods of a state in a year |
| `is_school_holiday` | Is this date in the school holidays? |
| `next_school_holidays` | The next (or current) school-holiday periods |
| `about` | Version, data coverage, sources and licenses |

States accept codes, `DE-` codes or names: `NW`, `DE-NW`, `NRW`, `Nordrhein-Westfalen`, `Thueringen`.

## Install

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

**Claude Code**

```bash
claude mcp add feiertage -- uvx --from git+https://github.com/drilongit/feiertage-mcp feiertage-mcp
```

**Claude Desktop / Cursor** (`claude_desktop_config.json` or `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "feiertage": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/drilongit/feiertage-mcp", "feiertage-mcp"]
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`)

```toml
[mcp_servers.feiertage]
command = "uvx"
args = ["--from", "git+https://github.com/drilongit/feiertage-mcp", "feiertage-mcp"]
```

## Example prompts

- "Is 31 October 2026 a holiday in Thüringen? And in NRW?"
- "How many working days does a Handwerker in Bayern have in December 2026, Saturdays included?"
- "When are the next Sommerferien in Berlin?"

## Data and coverage

| Data | Coverage | Source | License |
|---|---|---|---|
| Public holidays | 1995 to 2100 | Computed from the Länder Feiertagsgesetze and the Einigungsvertrag ([SOURCES.md](SOURCES.md)) | Laws are official works, § 5 UrhG |
| School holidays | Dec 2019 to May 2031 | [OpenHolidays API](https://www.openholidaysapi.org) snapshot | [ODbL 1.0](DATA_LICENSE.md) |

Future years apply current law; parliaments can change it. Future school holidays can still be
changed by the states. For anything critical, confirm with the state's Kultusministerium.
Informational only, no legal advice.

`scope` in results: `statewide`, `partial` (only some municipalities, e.g. Fronleichnam in parts of
Sachsen and Thüringen), `local` (Augsburger Friedensfest). Only `statewide` holidays count in
`is_public_holiday` and `count_working_days`.

## Security

- No network access at runtime, no file paths from the client, no shell, no eval.
- All inputs are validated (ISO dates, year range, state allow-list, range limit of about 10 years).
- Only dependency: the official `mcp` Python SDK.
- See [SECURITY.md](SECURITY.md) for the threat model and how to report issues.

## Development

```bash
uv venv && uv pip install -e ".[test]"
pytest            # unit tests + cross-checks against python-holidays and OpenHolidays
ruff check .
python scripts/build_data.py 2020 2031   # refresh school holidays (maintainers only)
```

---

## Deutsch

Ein [MCP](https://modelcontextprotocol.io)-Server für **gesetzliche Feiertage je Bundesland** und
**Schulferien**, nutzbar in Claude, Cursor, Codex und jedem anderen MCP-Client. Läuft offline, nur
lesend, ohne API-Key und ohne Netzwerkzugriff.

### Wozu

Sprachmodelle liegen bei deutschen Feiertagen oft daneben: Fronleichnam gilt nicht bundesweit, der
Reformationstag ist im Norden erst seit 2018 Feiertag, Berlin hat seit 2019 den Frauentag,
Mecklenburg-Vorpommern seit 2023, und Mariä Himmelfahrt gilt in Bayern nur in einem Teil der
Gemeinden. Dieser Server berechnet die Feiertage aus den Feiertagsgesetzen und liefert exakte
Antworten mit Quelle. Praktisch für Terminplanung, Liefertermine, Handwerk, Lohnabrechnung und Urlaub.

### Werkzeuge

| Tool | Funktion |
|---|---|
| `list_states` | Die 16 Bundesländer mit Kürzel |
| `get_public_holidays` | Feiertage eines Jahres und Bundeslands (optional auch nur teilweise geltende) |
| `holiday_overview` | Alle Feiertage eines Jahres mit den Ländern, in denen sie gelten |
| `is_public_holiday` | Ist das Datum in diesem Land ein Feiertag? |
| `next_public_holidays` | Die nächsten N Feiertage ab einem Datum |
| `count_working_days` | Arbeitstage zwischen zwei Daten ohne Wochenenden und Feiertage (Samstag optional) |
| `get_school_holidays` | Schulferien eines Landes in einem Jahr |
| `is_school_holiday` | Liegt das Datum in den Schulferien? |
| `next_school_holidays` | Die nächsten (oder laufenden) Ferien |
| `about` | Version, Datenabdeckung, Quellen, Lizenzen |

### Installation

Siehe oben unter **Install**: dieselben Befehle für Claude Code, Claude Desktop, Cursor und Codex.

### Beispiel-Fragen

- „Ist der 31.10.2026 in Thüringen ein Feiertag? Und in NRW?"
- „Wie viele Arbeitstage hat ein Handwerksbetrieb in Bayern im Dezember 2026, mit Samstagen?"
- „Wann sind die nächsten Sommerferien in Berlin?"

### Daten

Feiertage werden für 1995 bis 2100 aus den Feiertagsgesetzen der Länder berechnet (Gesetze sind
amtliche Werke nach § 5 UrhG, Quellen in [SOURCES.md](SOURCES.md)). Schulferien stammen aus einem
Abzug der [OpenHolidays API](https://www.openholidaysapi.org) (Dez. 2019 bis Mai 2031) unter
[ODbL 1.0](DATA_LICENSE.md). Künftige Jahre folgen dem heutigen Recht; Gesetze und Ferientermine
können sich ändern. Wichtige Termine bitte beim Kultusministerium des Landes prüfen. Keine Rechtsberatung.

## License / Lizenz

Code: MIT. School-holiday data: ODbL 1.0, © OpenHolidays API contributors. See [DATA_LICENSE.md](DATA_LICENSE.md).