Skip to main content
Glama
feiertage-mcp

feiertage-mcp

feiertage-mcp

CI

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.

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:

$ 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:

$ 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

Related MCP server: OpenHolidays MCP

How it fits together

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):

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

Claude Code:

claude mcp add feiertage -- npx -y feiertage-mcp

or in a project's .mcp.json:

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

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

{
  "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

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.

$ 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.

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

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. 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.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Public holiday data for 30+ countries. Check holidays, working days, and full calendars via AI assistants like Claude and Cursor.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to look up public and school holidays across roughly 30 European countries for any date range, including localized holiday names, nationwide status, and regional subdivision coverage. Also lists covered countries and their subdivisions so school-term queries can be scoped to a specific region.
      89 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to query German public holidays by Bundesland and school holidays, check whether dates are holidays, find upcoming holidays, and count working days using offline, sourced data.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to look up Austrian public holidays for any year, school holidays per federal state for 2026/27, the 2026 small-business VAT threshold, and SVS 2026 contribution rates including a rough estimate from annual profit. Runs locally over stdio with no dependencies.
      5
      MIT