📅 Public Holidays & Working Days MCP Server

Public Holidays & Working Days MCP Server gives Claude, ChatGPT, Cursor, VS Code and any other MCP client 7 read-only tools for the public holidays of 207 countries and their states and regions. It tells whether a date is a day off, lists the year's holidays, gives the next ones, counts working days between two dates and finds long weekends and bridge days. Dates are computed inside the server from the open-source date-holidays project, so nothing waits on an outside API.

Ask Claude "how many working days does May 2027 have in Belgium?" and it calls holiday_count_working_days. The reply is 19: 31 calendar days, minus 10 weekend days and 2 holidays on weekdays, Ascension Day on 6 May and Whit Monday on 17 May. Labour Day lands on a Saturday that year, so it costs nothing. You get the figure and the reasoning in one go, without counting squares on a calendar.

Quick start

1. Copy your Apify API token from Apify Console > Settings > API & Integrations.
2. Point your MCP client at https://mrbridge--public-holidays-mcp.apify.actor/mcp with that token, as a Bearer header, or as ?token= in claude.ai and ChatGPT. The Connect section has every recipe.
3. Ask in plain language, for example "Which long weekends does Spain get in 2027?"

What this server exposes

This server answers public holiday questions for 207 countries and their states and regions, in 7 read-only tools: the holidays of a year, whether a date is a holiday, the next holidays from a date, the working days between two dates, long weekends with optional bridge days, and the lists of covered countries and regions with their codes. It does not call any outside API. The dates are computed inside the Actor from the open-source date-holidays package (version 3.37.0, data of 2026-09-20), so the same question always gets the same answer and no source can rate-limit it. It needs no credentials and no third-party key: you connect with your Apify token, and each successful call is billed as one event. On top of the events you pay the platform usage of your own Standby run, billed to your Apify account: the memory set for the run while the server is up, idle time included, until it stops at its idle timeout (see Pricing). The holiday data is licensed CC BY-SA 3.0, and every answer carries the credit, the licence link and the Wikipedia articles the data of that country comes from.

Tools

Tool	What it answers	Billed event
holiday_list	List the holidays of a country or region for one year	tool-read
holiday_check	Check whether a date is a holiday	tool-read
holiday_next	Next holidays from a date	tool-read
holiday_count_working_days	Count working days between two dates	tool-action
holiday_list_long_weekends	Long weekends and bridge days of a year	tool-action
holiday_list_countries	Countries covered by the holiday data	tool-read
holiday_list_regions	States and regions of one country	tool-read

holiday_list: List the holidays of a country or region for one year

Use this when you need the public holidays (or bank, school, optional and observance days) of one country, state or region for a whole year, for example "Which public holidays does France have in 2027?" or "Holidays in Bavaria this year". Do not use for one date (holiday_check), the next upcoming days (holiday_next) or counting working days (holiday_count_working_days). Parameters: country (code or name, example "FR"), state and region (optional, add regional days, example "BY"), year (1970 to 2076, default this year), types (default ["public"]), limit (1 to 100, default 50), offset, response_format ("concise" or "detailed" with the local name and the rule). Each day has its date, end_date, weekday, English name, type, scope (national or regional), substitute (observed day) and partial_day. Computed offline from date-holidays (CC BY-SA 3.0), no upstream call.

Parameter	Type	Required	Example
country	string	yes	"FR"
state	string	no	"BY"
region	string	no	"A"
year	integer	no	2027
types	array of string	no	["public"]
limit	integer	no	50
offset	integer	no	0
response_format	"concise" or "detailed"	no	"concise"

Returns { place, year, types[], holidays[], pagination, notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_check: Check whether a date is a holiday

Use this when you need to know whether one date is a public holiday (or a bank, school, optional or observance day) in a country, state or region, for example "Is 14 July 2027 a holiday in France?" or "Is Monday 5 July 2027 a day off in the US?". Do not use for a whole year (holiday_list) or for counting days between two dates (holiday_count_working_days). Parameters: date (YYYY-MM-DD, 1970 to 2076, example "2027-07-14"), country (code or name, example "FR"), state and region (optional), types (default ["public"]), response_format. Answers is_holiday, day_off ("whole", "part" for a holiday from 14:00 or until 12:00, or "none"), the matching days (multi-day holidays included) and, apart, the days of other types on that date. A "no" is a valid answer. Computed offline from date-holidays (CC BY-SA 3.0).

Parameter	Type	Required	Example
date	string	yes	"2027-07-14"
country	string	yes	"FR"
state	string	no	"BY"
region	string	no	"A"
types	array of string	no	["public"]
response_format	"concise" or "detailed"	no	"concise"

Returns { place, date, weekday, types[], is_holiday, day_off, holidays[], other_holidays[], types_without_data[], notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_next: Next holidays from a date

Use this when you need the next public holidays (or bank, school, optional or observance days) of a country, state or region from a date, for example "When is the next public holiday in Germany?" or "Next three bank holidays in England". Do not use for a whole year (holiday_list) or one given date (holiday_check). Parameters: country (code or name, example "GB"), state and region (optional, example "ENG"), from_date (YYYY-MM-DD, counted itself, default today in UTC), limit (1 to 25, default 5), types (default ["public"]), response_format. Searches the year of from_date and the two next years. Each day comes with days_until from from_date, and a holiday already running on from_date comes first with in_progress true. Computed offline from date-holidays (CC BY-SA 3.0).

Parameter	Type	Required	Example
country	string	yes	"FR"
state	string	no	"BY"
region	string	no	"A"
from_date	string	no	"2027-08-01"
limit	integer	no	5
types	array of string	no	["public"]
response_format	"concise" or "detailed"	no	"concise"

Returns { place, from_date, types[], holidays[], notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_count_working_days: Count working days between two dates

Use this when you need the number of working days between two dates in a country, state or region, holidays and weekends removed, for example "How many working days between 1 and 31 May 2027 in Belgium?". Do not use for listing holidays (holiday_list) or checking one date (holiday_check). Parameters: start_date and end_date (YYYY-MM-DD, both counted, at most 732 days apart, example "2027-05-01"), country (code or name, example "BE"), state and region (optional), weekend_days (default ["saturday", "sunday"]), types (holiday types removed, default ["public"]), response_format ("detailed" adds the holidays that fell on a weekend). A holiday on a weekend day is not removed twice, a multi-day holiday removes each of its whole days, and part-days (from 14:00, until 12:00) are listed but not removed. Computed offline from date-holidays (CC BY-SA 3.0).

Parameter	Type	Required	Example
start_date	string	yes	"2027-05-01"
end_date	string	yes	"2027-05-31"
country	string	yes	"FR"
state	string	no	"BY"
region	string	no	"A"
weekend_days	array of string	no	["saturday","sunday"]
types	array of string	no	["public"]
response_format	"concise" or "detailed"	no	"concise"

Returns { place, start_date, end_date, weekend_days[], types[], calendar_days, weekend_days_count, holiday_days_count, working_days, holidays_on_working_days[], partial_days_not_subtracted[], holidays_on_weekends[], types_without_data[], notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_list_long_weekends: Long weekends and bridge days of a year

Use this when you need the long weekends of a year in a country, state or region, and optionally the one-day bridges that make a longer break, for example "Which long weekends does Spain get in 2027?" or "Where can I bridge a day in France in 2027?". Do not use for the plain list of holidays (holiday_list) or a count of working days (holiday_count_working_days). Parameters: country (code or name, example "FR"), state and region (optional), year (1970 to 2076, default this year), min_days (3 to 9, default 3), include_bridges (default false, adds spans that need one working day off, named in bridge_day), weekend_days (default ["saturday", "sunday"]), types (default ["public"]). A long weekend is a run of days off (weekend days and whole-day holidays) of at least min_days with a holiday of the year in it. Computed by this server from date-holidays data (CC BY-SA 3.0).

Parameter	Type	Required	Example
country	string	yes	"FR"
state	string	no	"BY"
region	string	no	"A"
year	integer	no	2027
min_days	integer	no	3
include_bridges	boolean	no	true
weekend_days	array of string	no	["saturday","sunday"]
types	array of string	no	["public"]

Returns { place, year, types[], weekend_days[], min_days, include_bridges, long_weekends[], notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_list_countries: Countries covered by the holiday data

Use this when you need to know which countries the holiday tools cover, or the code of a country, for example "Which countries does the holiday data cover?" or "Is Kenya covered?". Do not use for the states or regions of one country (holiday_list_regions) or for holidays themselves (holiday_list). Parameters: query (optional start of a word of the name, in English or the local language, or a two-letter code listed first, example "germany"), limit (1 to 250, default 50), offset, response_format ("detailed" adds the local name, languages, time zones, regions count and the weekly day off recorded in the data). Returns the ISO code, the English name and the number of states with their own holidays. From the date-holidays data (CC BY-SA 3.0), no upstream call.

Parameter	Type	Required	Example
query	string	no	"germany"
limit	integer	no	50
offset	integer	no	0
response_format	"concise" or "detailed"	no	"concise"

Returns { countries[], pagination, notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

holiday_list_regions: States and regions of one country

Use this when you need the states, provinces and regions that have their own holidays in one country, with the codes the other holiday tools accept, for example "Which German states have their own holidays?" or "What is the code for Bavaria?". Do not use for the list of countries (holiday_list_countries) or for the holidays themselves (holiday_list). Parameters: country (code or name, example "DE"), limit (1 to 100, default 60), offset, response_format ("detailed" adds the local name of each state). Each state has its code (mostly the ISO 3166-2 subdivision code), full_code ("DE-BY") and the regions inside it. From the date-holidays data (CC BY-SA 3.0), no upstream call.

Parameter	Type	Required	Example
country	string	yes	"DE"
limit	integer	no	60
offset	integer	no	0
response_format	"concise" or "detailed"	no	"concise"

Returns { place, states[], pagination, notes[], attribution }. Upstream: date-holidays (offline). Cache: not cached. Read-only.

Connect

Endpoint (Streamable HTTP): https://mrbridge--public-holidays-mcp.apify.actor/mcp

Every client authenticates with your Apify API token, found in Apify Console > Settings > API & Integrations. Clients that support custom headers send it as Authorization: Bearer <token>. The others use the ?token= URL variant, which must be treated as a secret: keep it out of commits, screenshots and shared logs.

Claude Code

$claude mcp add --transport http public-holidays "https://mrbridge--public-holidays-mcp.apify.actor/mcp" --header "Authorization: Bearer ${APIFY_TOKEN}"

Cursor, VS Code and other JSON configurations

{
  "mcpServers": {
    "public-holidays": {
      "type": "http",
      "url": "https://mrbridge--public-holidays-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer ${APIFY_TOKEN}"
      }
    }
  }
}

claude.ai and Claude Desktop

Add a custom connector with the URL https://mrbridge--public-holidays-mcp.apify.actor/mcp?token=YOUR_APIFY_TOKEN and no authentication. Prefilled link (replace the token placeholder before saving): add Public Holidays & Working Days MCP Server to Claude.

ChatGPT (developer mode)

Settings > Apps > Create, URL https://mrbridge--public-holidays-mcp.apify.actor/mcp?token=YOUR_APIFY_TOKEN, authentication "No authentication". ChatGPT snapshots the tool list: after a server update, an admin has to click Refresh on the app.

OpenAI Responses API

{
  "type": "mcp",
  "server_label": "public_holidays",
  "server_url": "https://mrbridge--public-holidays-mcp.apify.actor/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_APIFY_TOKEN"
  },
  "require_approval": "never"
}

Add allowed_tools to restrict the tool list. Tool calls must finish within about 60 seconds on this API, and every tool of this server answers in under 50 seconds.

Anthropic Messages API

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mrbridge--public-holidays-mcp.apify.actor/mcp",
      "name": "public-holidays",
      "authorization_token": "YOUR_APIFY_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "public-holidays"
    }
  ]
}

Send the beta header anthropic-beta: mcp-client-2025-11-20.

One-click OAuth alternative

https://mcp.apify.com/?tools=mrbridge/public-holidays-mcp connects through Apify OAuth without a token. It exposes the Actor as a single tool rather than the granular tools listed above.

Cost control

Each Standby run has a spending limit (maxTotalChargeUsd). When a call uses the last of it, the result is still returned, and later calls in that run answer CHARGE_LIMIT_REACHED until the limit is raised.

Why use Public Holidays & Working Days MCP Server

Holiday questions look simple until a weekend or a regional day gets in the way. Each tool handles one of those questions directly, so the model never counts dates by itself.

• No outside API. The rules ship inside the server. Results take a few milliseconds of computing, with no rate limit or source outage, and the same question always gets the same reply.
• States and regions. 207 countries, with the states, provinces and cantons that keep their own days. Pass Bavaria or Quebec and its local holidays join the national ones.
• Five day types. Public holidays by default, plus bank, school, optional and observance days on request. When the data holds nothing for a type, you are told so rather than given a plain "no".
• Awkward dates handled. Observed (substitute) days, part-days such as Christmas Eve from 14:00 in Germany, Eid spread over three or four days in the Gulf, and weekends other than Saturday and Sunday.
• Names you already use. "Italy", "UK", "Holland" or "DE-BY" work as well as ISO codes. An ambiguous name comes back with the candidates.
• Credit included. Every result carries the CC BY-SA 3.0 credit with its licence link, plus the Wikipedia articles behind that country's data, ready to travel with it.

Pricing (Pay-per-Event)

Event	Charged when	Price
apify-actor-start	run start (platform default)	see the Store page
tool-read (primary event)	each successful read tool call	see the Store page
tool-action	each successful call of a detailed or computed tool	see the Store page

Never charged: initialize, tools/list, pings, readiness probes, and any call that ends in an error (invalid input, not found, upstream failure, timeout, spending limit).

Platform usage comes on top of these events. This server runs in Apify Standby mode, and you also pay the platform usage of your own Standby run, billed to your Apify account like any other run: the memory set for the Standby run, for as long as the server is up, idle time included, until the run stops at its idle timeout. The Apify pay-per-event documentation says so: "For runs in Standby mode, users always pay the platform usage costs in addition to the event charges."

Limits, caveats and attribution

• Not an official calendar. Dates come from the rules of date-holidays, a community project mostly built from Wikipedia articles. They are right for most countries and most years, but a government can add or move a day at short notice. Check an official source before a legal, payroll or travel decision.
• Regional days need a state. Without state, answers hold the national days only, and the notes say how many states the country has. Pass state (and region where one exists, such as a city) to add the local days. holiday_list_regions gives the codes.
• Observed days. When a holiday falls on a weekend and the law moves the day off, the moved day is a separate entry with substitute: true, and the original date stays listed. This happens only where the date-holidays rules for that place say so.
• Types. public is the default. bank (banks and offices closed), school (schools closed), optional (most people take the day off) and observance (no paid day off) come only when you ask for them in types. The data has school days for 8 countries and bank days for 30. When it has nothing for a type you ask, the answer says so (types_without_data, or NOT_FOUND without a charge) instead of a plain "no".
• Part-days. Some days off start in the afternoon (partial_day, starts_at), such as Christmas Eve from 14:00 in Germany. Others end at noon (ends_at), such as the last day of the Turkish bayrams. Both are listed but never removed from working days, and holiday_check answers day_off: "part" for them.
• Lunar calendars. Islamic holidays come from a computed calendar and can be one or two days off the date announced after the local moon sighting. Days that begin at sunset show starts_at: "18:00 the day before".
• Years. 1970 to 2076, the years where every calendar of the data (Gregorian, Islamic, Hebrew, Chinese) is computed. Weekends default to Saturday and Sunday, pass weekend_days for another working week.
• Sizes. Lists are paged with limit and offset. A working-day count covers at most 732 days.
• Attribution. Each answer carries an attribution block: the source (date-holidays by commenthol and contributors), the package and data versions, the licence (CC BY-SA 3.0) with its link, the project attribution file, the Wikipedia articles behind the data of the country (sources), and notices with the credit line, the changes this server makes and the non-affiliation line. Keep it with the data when you pass it on.

Data terms

The holiday data of date-holidays is licensed under CC BY-SA 3.0, and most of it comes from Wikipedia articles listed in the project attribution file. The package code is under the ISC licence. What this server returns is an adaptation of that data (dates computed for your place and period, fields renamed, working days counted), shared under the same licence. Every answer carries the attribution and the CC BY-SA notice. By using this server you agree to:

• credit date-holidays and its sources, with the licence link, wherever you show or publish the data (the attribution block of each answer has the text and the links),
• share what you build from the data under CC BY-SA 3.0 or a compatible licence, as the ShareAlike clause requires,
• leave out any wording that suggests the date-holidays authors or Wikipedia endorse you or this server.

This server is not affiliated with or endorsed by date-holidays, its authors or Wikipedia. The fee for this server pays for the service (hosting, computing, normalisation), not for a licence on the data, which stays under CC BY-SA 3.0 with no added restriction.

Use cases

Timesheets and project plans. Count the working days of a month or a quarter for a country or a state, with each weekday holiday named. For a team that works Sunday to Thursday, pass weekend_days: ["friday", "saturday"].

Long weekends. "Where can I bridge a day in France in 2027?" Ascension Day falls on Thursday 6 May, so taking Friday 7 May off gives four days in a row, 6 to 9 May. Armistice Day on Thursday 11 November works the same way.

Meetings across borders. Before you book a call or a delivery, check the date where the other side works. "Is Monday 5 July 2027 a day off in the US?" Yes: Independence Day falls on a Sunday that year, so the observed day moves to Monday.

UK bank holidays and countdowns. "Next two bank holidays in England from 1 August 2027" returns the Summer bank holiday on 30 August, 29 days away, then Christmas Day, 146 days out. UK bank holidays are the default public type, so no filter is needed.

Trips and staffing. List the holidays of a destination over the dates of a trip, or the regional days of every state where your shops or teams sit, with holiday_list and the codes from holiday_list_regions.

Frequently asked questions

How much does it cost?

Each successful tool call is one event, priced on the Pricing tab for your Apify plan: tool-action for holiday_count_working_days and holiday_list_long_weekends, tool-read for every other tool. Paid Apify plans get lower prices. On the free plan, a read costs 0.005 USD and an action 0.01 USD, so 100 reads come to 0.50 USD in events. Apify also charges its standard apify-actor-start event when your Standby run starts.

On top of the events, your Apify account pays the platform usage of your own Standby run while the server is up, idle minutes included, as with every pay-per-event Standby Actor. The run stops after about 5 minutes without a call.

Errors are never charged. An unknown country or an impossible date costs nothing, nor does a day type the data does not hold. A plain "no" from holiday_check is a real reply and counts as one call. Each run also has a spending limit, maxTotalChargeUsd.

Are these official dates?

No. They are computed from the rules of date-holidays, a community project built mostly from Wikipedia articles. They hold for most countries and years, but a government can add or move a day at short notice. Check an official source before any legal or payroll decision.

Is my country covered?

207 countries are, with 364 states and provinces. Ask holiday_list_countries with a name or a code. A country missing from the data, such as Oman, gets a NOT_FOUND by name, never a neighbour's holidays, and no charge. Without state, results hold national days only: add state (and region where one exists, such as a city) for the local ones, with codes from holiday_list_regions.

Can I reuse what the server returns?

Yes, under CC BY-SA 3.0. Credit date-holidays and its sources with the licence link (the attribution block of each reply has both), and share what you build from the data under the same licence. The fee pays for running the service, not for a licence on the data. This server is not affiliated with or endorsed by date-holidays, its authors or Wikipedia.

Why is the first call slower?

The first call after a quiet period starts your Standby run, which takes a few seconds. After that, everything is computed in memory, with no outside service to wait for.

Your feedback

Found a wrong date, or a place the data misses? Open an issue on the Issues tab.

More tools and data studies from the same team: mr-bridge.com.

Changelog

• 0.1.3: Output, dataset and key-value store schemas, as Apify asks for publication: the Output tab of a run started from the Console shows the connection details and one row per tool.
• 0.1.2: the Input tab shows the endpoint and how to connect an AI client, and a run started from the Console outputs the connection details and the tool list
• 0.1.1: pricing events tool-read and tool-action
• 0.1.0: initial build, server name aligned with the Store title (private, unpublished)
  • the overview names the platform usage of your own Standby run next to the per-call event, as the Pricing section does