Skip to main content
Glama
feiertage-mcp

feiertage-mcp

README.md
# feiertage-mcp

[![CI](https://github.com/syedaayanahmed2001/feiertage-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/syedaayanahmed2001/feiertage-mcp/actions/workflows/ci.yml)
<!-- [![npm](https://img.shields.io/npm/v/feiertage-mcp.svg)](https://www.npmjs.com/package/feiertage-mcp) -->

German public holidays differ by state and change over time, and LLM assistants often get them wrong; this MCP server computes them by rule for all 16 Bundesländer and plans bridge days (Brückentage) and leave around them.

<!-- demo gif goes here -->

No holiday API, no dataset: every date comes from the rules in the state holiday laws, so it
works offline for any year from 2000 to 2100. There is also a small CLI.

## Example

> **You:** Which bridge days are there in Bavaria in 2027?
>
> The assistant calls `bridge_days` with `{ "state": "BY", "year": 2027 }`.

The same query from the terminal, output pasted verbatim:

```text
$ npx feiertage-mcp --cli bridge-days BY 2027
Bridge days in Bayern (BY), 2027, using up to 1 leave day each: 2 found

  Take off: Fri 2027-05-07, 1 leave day
  Days off: Thu 2027-05-06 to Sun 2027-05-09, 4 days (4.00 per leave day)
  Holidays: Christi Himmelfahrt (Thu 2027-05-06)

  Take off: Fri 2027-05-28, 1 leave day
  Days off: Thu 2027-05-27 to Sun 2027-05-30, 4 days (4.00 per leave day)
  Holidays: Fronleichnam (Thu 2027-05-27)
```

With a budget, `plan_leave` finds the longest stretches instead:

```text
$ npx feiertage-mcp --cli plan-leave BY 2027 5 --from 5 --to 6 --limit 3
Leave options in Bayern (BY), 2027, up to 5 leave days, months 5-6. Each option is an alternative.

  1. Take off: the working days from Mon 2027-05-03 to Mon 2027-05-10, 5 leave days
     Days off: Sat 2027-05-01 to Mon 2027-05-10, 10 days (2.00 per leave day)
     Holidays: Tag der Arbeit (Sat 2027-05-01), Christi Himmelfahrt (Thu 2027-05-06)

  2. Take off: the working days from Fri 2027-05-14 to Fri 2027-05-21, 5 leave days
     Days off: Fri 2027-05-14 to Sun 2027-05-23, 10 days (2.00 per leave day)
     Holidays: Pfingstmontag (Mon 2027-05-17)

  3. Take off: the working days from Mon 2027-05-31 to Fri 2027-06-04, 5 leave days
     Days off: Sat 2027-05-29 to Sun 2027-06-06, 9 days (1.80 per leave day)
     Holidays: none, weekends only
```

## How it fits together

```mermaid
flowchart LR
  Client["MCP client<br/>Claude Desktop, Claude Code, Cursor"] -- "stdio, JSON-RPC" --> Server["server.ts<br/>4 tools, zod schemas"]
  Terminal["Terminal"] -- "--cli" --> CLI["cli.ts"]
  Server --> Tools["tools.ts<br/>shared handlers"]
  CLI --> Tools
  Tools --> Planner["planner/<br/>bridge days, leave windows"]
  Tools --> Engine["engine/<br/>rules, Easter, dates"]
  Planner --> Engine
```

`engine/` and `planner/` are pure functions with no dependencies. The server and the CLI call
the same handlers, so `--cli ... --json` prints exactly what the MCP tool returns.

## Install

Requires Node.js 20 or later. The server speaks MCP over stdio.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "feiertage": {
      "command": "npx",
      "args": ["-y", "feiertage-mcp"]
    }
  }
}
```

**Claude Code**:

```sh
claude mcp add feiertage -- npx -y feiertage-mcp
```

or in a project's `.mcp.json`:

```json
{
  "mcpServers": {
    "feiertage": {
      "command": "npx",
      "args": ["-y", "feiertage-mcp"]
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "feiertage": {
      "command": "npx",
      "args": ["-y", "feiertage-mcp"]
    }
  }
}
```

To run from a local checkout instead, build it (`npm ci && npm run build`) and use
`"command": "node", "args": ["/absolute/path/to/feiertage-mcp/dist/bin.js"]`.

## Tools

All tools are read-only. `state` is one of `BW BY BE BB HB HH HE MV NI NW RP SL SN ST SH TH`,
`year` is 2000-2100, and every tool takes an optional `includeLocal` (default `false`) that adds
the Augsburger Friedensfest. Results are JSON.

| Tool | Inputs | Returns |
|------|--------|---------|
| `list_holidays` | `state`, `year` | `{ state, stateName, year, includeLocal, count, holidays[] }`; each holiday has `date`, `weekday`, `id`, `name` (German), `nameEn`, `scope` (`national`, `state`, `one-off`, `local`) and sometimes a `note` |
| `is_holiday` | `date` (`YYYY-MM-DD`), `state` | `{ date, state, weekday, isWeekend, isHoliday, isDayOff, holidays[] }` |
| `bridge_days` | `state`, `year`, `maxLeaveDays` (1-3, default 1) | `{ ..., count, bridges[] }`: runs of working days with a day off directly before and after |
| `plan_leave` | `state`, `year`, `leaveDays` (1-60), `fromMonth`, `toMonth` (1-12), `limit` (1-20, default 5) | `{ ..., note, suggestions[] }`: non-overlapping alternatives, each using at most `leaveDays` |

Each bridge or suggestion has `leaveDates[]`, `leaveDays`, `blockStart`, `blockEnd`,
`totalDaysOff`, `efficiency` (days off per leave day) and the `holidays[]` inside the block.
`plan_leave` ranks by total days off, then fewer leave days, then date. A block can run into the
neighbouring year (leave on 28-31 December 2026 in Bavaria gives 25 December to 3 January).

## CLI

```text
feiertage-mcp --cli holidays STATE YEAR
feiertage-mcp --cli is-holiday DATE STATE
feiertage-mcp --cli bridge-days STATE YEAR [--max-leave N]
feiertage-mcp --cli plan-leave STATE YEAR DAYS [--from M] [--to M] [--limit N]
feiertage-mcp --cli help
```

Add `--local` for the Augsburger Friedensfest and `--json` for the raw tool output.

```text
$ npx feiertage-mcp --cli is-holiday 2026-10-31 NI
2026-10-31 (Saturday) is a public holiday in Niedersachsen (NI): Reformationstag (Reformation Day).
```

## How holidays are computed

Easter Sunday comes from the anonymous Gregorian algorithm (Meeus/Jones/Butcher). The movable
holidays are offsets from it: Karfreitag -2, Ostermontag +1, Christi Himmelfahrt +39,
Pfingstsonntag +49, Pfingstmontag +50, Fronleichnam +60. Buß- und Bettag is the Wednesday
before 23 November. Everything else is a fixed date. German holidays that fall on a weekend are
not moved to a weekday, so none are.

| Holiday | Date | States |
|---------|------|--------|
| Neujahr, Karfreitag, Ostermontag, Tag der Arbeit, Christi Himmelfahrt, Pfingstmontag, Tag der Deutschen Einheit, 1. and 2. Weihnachtstag | | all 16 |
| Heilige Drei Könige | 6 Jan | BW, BY, ST |
| Internationaler Frauentag | 8 Mar | BE since 2019, MV since 2023 |
| Ostersonntag, Pfingstsonntag | Easter, Easter +49 | BB (always Sundays; Brandenburg's law lists them) |
| Fronleichnam | Easter +60 | BW, BY, HE, NW, RP, SL |
| Augsburger Friedensfest | 8 Aug | city of Augsburg only; returned only with `includeLocal` |
| Mariä Himmelfahrt | 15 Aug | SL; BY (see limitations) |
| Weltkindertag | 20 Sep | TH since 2019 |
| Reformationstag | 31 Oct | BB, MV, SN, ST, TH; HB, HH, NI, SH since 2018; every state in 2017 (500th anniversary) |
| Allerheiligen | 1 Nov | BW, BY, NW, RP, SL |
| Buß- und Bettag | Wed before 23 Nov | SN |
| One-offs in Berlin | 8 May 2020, 8 May 2025, 17 June 2028 | BE |

Resulting counts for 2026 and 2027: BW 12, BY 13, BE 10, BB 12, HB 10, HH 10, HE 10, MV 11,
NI 10, NW 11, RP 11, SL 12, SN 11, ST 11, SH 10, TH 11 (Berlin has 11 in 2025 and 2028). Minus
Brandenburg's two Sundays, this matches the count table on Wikipedia; the tests check it.

Edge cases covered by tests: two holidays on one date (1 May 2008 was also Ascension Day),
leap years (2000 is one, 2100 is not), Buß- und Bettag on 22 November (2028), Reformationstag
2017 in states that already had it, and leave blocks that cross New Year.

### Sources

Checked on 22 November 2026.

- Wikipedia, [Gesetzliche Feiertage in Deutschland](https://de.wikipedia.org/wiki/Gesetzliche_Feiertage_in_Deutschland): per-state table, counts, Bavarian and Augsburg footnotes, Berlin one-offs.
- Wikipedia, [Public holidays in Germany](https://en.wikipedia.org/wiki/Public_holidays_in_Germany): Reformation Day permanent in HB, HH, NI, SH from 2018; Easter and Whit Sunday in Brandenburg.
- Berlin, Gesetz über die Sonn- und Feiertage § 1 ([text](https://umwelt-online.de/recht/arbeitss/arbeitsrecht/laender/bln/feiertg.htm)): Frauentag, 17 June 2028; [berlin.de on 8 May 2025](https://www.berlin.de/en/news/9188766-5559700-einmaliger-feiertag-am-8-mai-2025.en.html), which also mentions 2020 and 2028.
- Thüringer Feier- und Gedenktagsgesetz § 2 ([text](https://umwelt-online.de/recht/arbeitss/arbeitsrecht/laender/th/feiertg.htm)): Weltkindertag, Reformationstag, Fronleichnam only by ordinance for Catholic municipalities.
- Mecklenburg-Vorpommern, [GVBl. M-V 2022 Nr. 31](https://www.dokumentation.landtag-mv.de/parldok/dokument/53736/gesetz_und_verordnungsblatt_2022_31.pdf): Frauentag added to the Feiertagsgesetz, first observed 2023.
- Brandenburg, Feiertagsgesetz (FTG) § 2 on [bravors.brandenburg.de](https://bravors.brandenburg.de/): Ostersonntag and Pfingstsonntag.
- Cross-check of dates and state lists: feiertage-deutschland.de for [2025](https://www.feiertage-deutschland.de/2025/), [2026](https://www.feiertage-deutschland.de/2026/), [2027](https://www.feiertage-deutschland.de/2027/).
- Easter: [anonymous Gregorian algorithm](https://en.wikipedia.org/wiki/Date_of_Easter#Anonymous_Gregorian_algorithm).

## Limitations

- **Municipal holidays are not modelled.** Fronleichnam is a holiday in some Catholic
  municipalities of Sachsen and Thüringen; it is not listed for those states.
- **Mariä Himmelfahrt in Bavaria** is a holiday only in municipalities with a predominantly
  Catholic population (about 1,700, including Munich and Augsburg). It is listed statewide, with a
  note on the entry. If you are in a Protestant-majority municipality, you do not get it.
- **Augsburger Friedensfest** applies to the city of Augsburg only and appears only with
  `includeLocal`.
- **School holidays are not included.** They are set by decree each year, not by rule. Days that
  are only school-free, such as Gründonnerstag in Baden-Württemberg or Buß- und Bettag in Bayern,
  are not public holidays and are not listed.
- **24 and 31 December are working days** by law, and the planner treats them that way. Many
  employers give them off; plan accordingly.
- **Future law changes** are not known in advance. One-off holidays are only included once
  enacted; the rules reflect the laws as of the date above.
- The planner assumes a Monday-to-Friday week.

## Development

```sh
npm ci
npm run typecheck   # tsc --noEmit, strict
npm run lint        # eslint (typescript-eslint, no-explicit-any)
npm test            # vitest
npm run build       # tsc to dist/
npm run smoke       # starts dist/bin.js over stdio and calls a tool
node dist/bin.js --cli bridge-days BY 2027
```

Layout: `src/engine` (dates, Easter, rule table), `src/planner` (bridge days, leave planner),
`src/tools.ts` (schemas and handlers), `src/server.ts`, `src/cli.ts`, `src/bin.ts`.

## How this was built: spec first

The requirements and acceptance criteria were written before the code, in
[docs/SPEC.md](docs/SPEC.md). Each requirement has an ID (ENG-, PLAN-, MCP-, CLI-, PKG-, DOC-), and
every test name starts with the ID it proves, for example `[PLAN-03] leave 28-31 Dec 2026 in
Bavaria gives 25 Dec 2026 to 3 Jan 2027`. Run `npx vitest run -t "PLAN-03"` to see one
requirement's tests.

## License

MIT, Syed Aayan Ahmed.