# holidays-mcp

**Real, official public holiday data for ~100 countries, free, in one command.**

```bash
pip install holidays-mcp   # or: uvx holidays-mcp
```

Then ask your agent: *"what are the public holidays in the US in 2026?"* or *"is December 25th 2026 a holiday in the US?"*

No API key. No signup. Free.

## Tools

| Tool | What the model sees it for |
|---|---|
| `get_public_holidays(country_code, year)` | Full list of a country's public holidays for a given year. "What are the holidays in Germany in 2026?", planning around a holiday calendar. |
| `is_public_holiday(country_code, date)` | Whether one specific date is a public holiday, and its name if so. "Is Dec 25 2026 a holiday in the US?", "is the office closed on this date?" |

Country codes are 2-letter ISO (US, GB, DE, FR, JP, ...) — Nager.Date covers roughly 100 countries with official holiday calendars, not every country worldwide. Dates are YYYY-MM-DD.

## Example

```
> is_public_holiday("US", "2026-12-25")
{
  "date": "2026-12-25",
  "country_code": "US",
  "country_name": "United States",
  "is_holiday": true,
  "holiday": {
    "local_name": "Christmas Day",
    "name": "Christmas Day",
    "types": ["Public", "Bank"]
  },
  "attribution": "Public holiday data by Nager.Date (date.nager.at)"
}
```

```
> get_public_holidays("US", 2026)
{
  "country_code": "US",
  "country_name": "United States",
  "year": 2026,
  "count": 17,
  "holidays": [
    {"date": "2026-01-01", "local_name": "New Year's Day", "name": "New Year's Day", "types": ["Public", "Bank"]},
    {"date": "2026-01-19", "local_name": "Martin Luther King, Jr. Day", "name": "Martin Luther King, Jr. Day", "types": ["Public", "Bank"]},
    ...
  ],
  "attribution": "Public holiday data by Nager.Date (date.nager.at)"
}
```

## How it's free

This server is part of the [Lulu Ads](https://getlulu.dev/publishers) network:
tool results may carry one clearly labeled, disclosed `sponsored` data field
(never instructions, never hidden). That sponsorship pays the hosting, so the
lookup stays free. Fail-open by design — if the ads backend is slow, down,
or (as with a local install) has no credentials at all, the tools behave
exactly like an unmonetized server.

Run your own MCP? The same one-line integration is open to every publisher —
[getlulu.dev/publishers](https://getlulu.dev/publishers), 70% rev share.

## Data

Public holiday data by [Nager.Date](https://date.nager.at), a free, keyless,
community-maintained holiday calendar API. This project is not affiliated
with Nager.Date.

## Self-hosting over HTTP

```bash
pip install fastmcp lulu-ads httpx uvicorn
MCP_TRANSPORT=http HOLIDAYS_LOCAL_DEV=1 python server.py   # serves http://localhost:8080/holidays/mcp
```