Ferien — German school holidays by year & federal state
Read-only MCP server returning German school holiday dates per federal state and year
- Pricing
- Open source
- Platforms
- CLI, API, Linux
- Runs
- Locally
- Version
- 0.1.0
- Listing updated
- today
Similar MCP servers
About Ferien — German school holidays by year & federal state
Ferien — German school holidays by year & federal state is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
The README says this server lets AI clients ask when German school holidays fall, per federal state and year. Queries always need one of the 16 two-letter state codes, because there is no nationwide list; the server can list holidays for a year, check whether a given date is a holiday, find the next holiday from a date, and list holidays overlapping a date range.
Data comes from the public ferien-api.de service, which the README describes as part of the bundesAPI project. No API key or login is needed. Holiday names are returned in German, each entry carries a holiday type such as Sommerferien or Osterferien, and results include the duration in days. The README warns that coverage varies by state and year, so an empty result may mean missing data, and it advises checking important dates against official sources.
The project is aimed at developers and agent builders who want school calendar lookups in an MCP-capable client. It is unofficial and not affiliated with ferien-api.de or bundesAPI, and it installs via PyPI and runs over stdio.
Install
Run in a terminal
claude mcp add ferien-mcp -- uvx ferien-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"ferien-mcp": {
"command": "uvx",
"args": [
"ferien-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"ferien-mcp": {
"command": "uvx",
"args": [
"ferien-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"ferien-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"ferien-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"ferien-mcp": {
"command": "uvx",
"args": [
"ferien-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"ferien-mcp": {
"command": "uvx",
"args": [
"ferien-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- ferien_list_holidays
- School holidays of one year in one federal state, with optional month filter
- ferien_is_holiday
- Checks whether a date is inside the school holidays in one state
- ferien_next_holiday
- Returns the next school holiday on or after a date
- ferien_holidays_between
- School holidays overlapping a date range (max about two years)
- ferien_list_states
- Lists all 16 German federal states
- ferien_health
- Reachability check of the upstream API
What it does
- Holidays by year and state
- Returns the school holidays of one German federal state for a given year, with an optional month filter.
- Holiday check for a date
- Tells whether a YYYY-MM-DD date falls inside the school holidays of a chosen state.
- Next holiday lookup
- Finds the next school holiday on or after a date, or the ongoing one if the date is already inside a holiday.
- Date range overlap query
- Lists school holidays overlapping a date range of up to about two years, including holidays crossing New Year.
- Read-only, no key required
- Only reads data from the upstream API and needs no account, key or login.
- Reachability health check
- Provides a single-request tool that reports whether the upstream API is ok, blocked or in error.
Good for
- Planning holiday travel or leave around a specific German state's school break
- Letting an AI assistant answer whether a given date is a school holiday in a state
- Finding the next school holiday from today for a scheduling workflow
- Pulling a year's holiday calendar for a state into a spreadsheet or planning tool
Pricing
Open source
Free and open source, installed from PyPI
Ferien — German school holidays by year & federal state FAQ
Does it cover all of Germany at once?
No. The README says there is no nationwide list, so every query needs one of the 16 state codes.
Do I need an API key?
No. The README says the upstream API needs no key or login.
What should I do if a request returns HTTP 429?
The README advises waiting a few minutes and retrying, since the upstream API rate-limits per IP.
Is this an official source?
No. The README states it is unofficial and not affiliated with ferien-api.de or the bundesAPI project.
Is Ferien — German school holidays by year & federal state free?
Yes. Ferien — German school holidays by year & federal state is open source, so you can use and self-host it for free.
How do I add Ferien — German school holidays by year & federal state to Claude Code?
Run this command in your terminal: claude mcp add ferien-mcp -- uvx ferien-mcp
What are the best alternatives to Ferien — German school holidays by year & federal state?
The closest alternatives to Ferien — German school holidays by year & federal state are Public Holidays Mcp, CalKit, WorkdayAPI, TidyData Tools and Türkiye Business Days & Public Holidays.
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.