# 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. Read-only MCP server returning German school holiday dates per federal state and year. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, Linux, macOS, Windows
- **Repository:** https://github.com/mohammad-abbasi-sh/ferien-mcp
- **MCP Registry name:** io.github.mohammad-abbasi-sh/ferien-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-19

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add ferien-mcp -- uvx ferien-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "ferien-mcp": {
      "command": "uvx",
      "args": [
        "ferien-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "ferien-mcp": {
      "command": "uvx",
      "args": [
        "ferien-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "ferien-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ferien-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "ferien-mcp": {
      "command": "uvx",
      "args": [
        "ferien-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "ferien-mcp": {
      "command": "uvx",
      "args": [
        "ferien-mcp"
      ]
    }
  }
}
```

## Tools

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

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

## Alternatives

- [Public Holidays Mcp](https://ai-powered.com/mcp/public-holidays-mcp-2): Public Holidays Mcp is a freemium MCP server for developer tools.
- [CalKit](https://ai-powered.com/mcp/calkit): CalKit is a freemium MCP server for developer tools.
- [WorkdayAPI](https://ai-powered.com/mcp/workdayapi): WorkdayAPI is a freemium MCP server for developer tools.
- [TidyData Tools](https://ai-powered.com/mcp/tidydata-tools): TidyData Tools is a freemium MCP server for developer tools.
- [Türkiye Business Days & Public Holidays](https://ai-powered.com/mcp/turkiye-business-days-and-public-holidays): Türkiye Business Days & Public Holidays is a free MCP server for productivity.

---
Source: https://ai-powered.com/mcp/ferien-german-school-holidays-by-year-and-federal-state
