MCP Server API Documentation

Access German school vacation and holiday data through the Model Context Protocol (MCP)

Version 1.0.0 Slug-based Access

Quick Start

Endpoint


            https://www.mehr-schulferien.de/mcp

Protocol

MCP (Model Context Protocol) over HTTP/JSON-RPC

Authentication

No authentication required (public read-only access)

Example API Request

Send a POST request to the MCP endpoint with a JSON-RPC payload to call any tool.

POST https://www.mehr-schulferien.de/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_school_details",
    "arguments": {
      "school_slug": "79713-josef-anton-sickinger-grundschule"
    }
  },
  "id": 1
}

Available Tools

📍 Location Navigation

get_countries

List all available countries

No parameters required

get_federal_states

List federal states of a country

country_slug: string

get_cities_by_state

List all cities in a federal state

country_slug, federal_state_slug

get_cities_by_country

List all cities of a country

country_slug: string

get_schools_by_city

List all schools in a city

city_slug: string

get_schools_by_federal_state

List ALL schools in a federal state

country_slug, federal_state_slug

get_counties

List all counties of a federal state

country_slug, federal_state_slug

get_location_hierarchy

Get full location hierarchy

location_slug, location_type

🏫 School Information

get_school_details

Complete school info with address & contact

school_slug: string

Returns: name, address, phone, email, homepage

search_schools

Search schools by name or keyword

query, federal_state_slug?, city_slug?

get_nearby_schools

Find schools within distance

school_slug, distance_meters

get_schools_by_zip

Find schools by zip code prefix

zip_prefix: string (3-5 digits)

📅 Vacations & Holidays

get_vacations

School vacation periods

location_slug, location_type, dates?

get_public_holidays

Public holidays for a location

location_slug, location_type, year

Supports: country, federal_state, city

get_all_periods

Combined vacations and holidays

location_slug, location_type, year

get_next_periods

Upcoming vacations and holidays

location_slug, location_type, count?

get_current_periods

Currently active periods

location_slug, location_type, date?

🌉 Vacation Planning

get_bridge_days

Calculate optimal bridge days

federal_state_slug, year

Returns efficiency percentage

check_bridge_days_availability

Check bridge days for multiple years

federal_state_slug, years[]

get_vacation_statistics

Vacation day statistics

location_slug, location_type, year

compare_vacation_schedules

Compare schedules between locations

location_slugs[], location_type, year

get_school_year_info

School year start and end dates

federal_state_slug, year

get_bewegliche_ferientage

Flexible vacation day info

school_slug, school_year

🔍 Search & Export

search_locations

Search any location by name

query, type?

get_location_by_slug

Get location details by slug

slug: string

validate_slug

Check if slug exists

slug: string

get_ical_url

Generate iCal subscription URL

location_slug, location_type

export_periods_json

Export periods as JSON

location_slug, type, dates

Common Slugs Reference

Countries

deutschland - Germany

Federal States

baden-wuerttemberg - Baden-Württemberg
bayern - Bavaria
berlin - Berlin
brandenburg - Brandenburg
bremen - Bremen
hamburg - Hamburg
hessen - Hesse
mecklenburg-vorpommern - Mecklenburg-Vorpommern
niedersachsen - Lower Saxony
nordrhein-westfalen - North Rhine-Westphalia
rheinland-pfalz - Rhineland-Palatinate
saarland - Saarland
sachsen - Saxony
sachsen-anhalt - Saxony-Anhalt
schleswig-holstein - Schleswig-Holstein
thueringen - Thuringia

Major Cities

muenchen - Munich
berlin - Berlin
hamburg - Hamburg
koeln - Cologne
frankfurt-am-main - Frankfurt
stuttgart - Stuttgart
duesseldorf - Düsseldorf
dortmund - Dortmund
essen - Essen
leipzig - Leipzig

Location Types

country - Country level
federal_state - Federal state level
county - County level
city - City level
school - School level

Example Usage

Get Public Holidays for Berlin 2025

curl -X POST https://www.mehr-schulferien.de/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_public_holidays","arguments":{"location_slug":"berlin","location_type":"federal_state","year":2025}},"id":1}'

Find Schools in Munich

curl -X POST https://www.mehr-schulferien.de/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_schools_by_city","arguments":{"city_slug":"muenchen"}},"id":2}'

Get School Contact Information

curl -X POST https://www.mehr-schulferien.de/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_school_details","arguments":{"school_slug":"79713-josef-anton-sickinger-grundschule"}},"id":3}'

Calculate Bridge Days for Bavaria 2025

curl -X POST https://www.mehr-schulferien.de/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_bridge_days","arguments":{"federal_state_slug":"bayern","year":2025}},"id":4}'

Integration Guide

For AI Assistants

This MCP server is designed to work seamlessly with AI assistants that support the Model Context Protocol. Configure your assistant to connect to the MCP endpoint, and it will automatically discover all available tools.

For Developers

Use standard HTTP POST requests with JSON-RPC format. All responses are JSON-formatted and optimized for programmatic access. The slug-based navigation ensures you never need internal database IDs.

Example Languages

Python: Use requests library
JavaScript: Use fetch or axios
Ruby: Use Net::HTTP or HTTParty
PHP: Use cURL or Guzzle
Go: Use net/http package

Best Practices

Rate Limiting

No strict rate limits for reasonable usage
Please cache responses when appropriate
Avoid unnecessary repeated queries

Performance Tips

Use specific location types to narrow searches
Request only the date ranges you need
Cache location slugs for repeated queries
Use batch operations when comparing multiple locations

Error Handling

Always check for error responses in the JSON-RPC result
Invalid slugs will return "not found" errors
Date parameters must be in YYYY-MM-DD format
Year parameters are typically limited to 2020-2030

Support & Contact

For API support and questions:

Note: This is a read-only API. All data modifications must be done through the main website's wiki interface.