business-day-mcp

MCP server for business-day arithmetic with country-aware holiday calendars (fastmcp + holidays).

What is this?

business-day-mcp exposes business-day math — "is today a business day?", "next business day after X", "how many business days between A and B?" — as tools an MCP client can call. Holiday calendars are provided by the holidays library and cover 60+ countries, with optional regional subdivisions. It is intended for use with MCP clients such as Claude Desktop, Kiro, and any other tool that speaks the Model Context Protocol. Requires Python >= 3.10.

Example questions it can answer:

• Is today a business day in Germany?
• When is the last business day of April 2026?
• How many business days between Apr 21 and May 5 in the US?

Features / Tools

• get_current_date — current date in a given IANA timezone.
• is_business_day — check whether a date is a business day for a country (+ optional subdivision).
• next_business_day / previous_business_day — step forward/backward by N business days.
• last_business_day_of_month — last business day of a given month.
• business_days_between — count business days between two dates.
• list_holidays — holidays for a country/year (+ optional subdivision).
• get_supported_countries — supported ISO 3166-1 alpha-2 codes and their subdivisions.
• get_supported_subdivisions — subdivisions and aliases for a single country.

All tools are read-only and safe to auto-approve.

Install

From the package

uvx business-day-mcp

Or persistent install:

pip install business-day-mcp

Run the server:

business-day-mcp
# or
python -m business_day_mcp

From source

git clone https://github.com/fbdo/business-day-mcp.git
cd business-day-mcp
uv sync --all-extras
uv run business-day-mcp

Run the test suite (coverage must stay ≥ 90%):

uv run pytest

Configure

Add to your mcp.json:

{
  "mcpServers": {
    "business-day-mcp": {
      "command": "uvx",
      "args": ["business-day-mcp"],
      "autoApprove": [
        "get_current_date",
        "is_business_day",
        "next_business_day",
        "previous_business_day",
        "last_business_day_of_month",
        "business_days_between",
        "list_holidays",
        "get_supported_countries",
        "get_supported_subdivisions"
      ]
    }
  }
}

From a local clone

Run uv sync --all-extras in the cloned repo first, then replace /absolute/path/to/business-day-mcp below with the clone's absolute path (you can copy the same autoApprove array from the package example above if desired):

{
  "mcpServers": {
    "business-day": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/business-day-mcp",
        "run",
        "business-day-mcp"
      ]
    }
  }
}

Usage Examples

The examples below show typical agent questions and the actual JSON returned by the server. Dates reflect the real 2025/2026 calendars from the holidays library.

Is this a business day?

"Is July 4, 2025 a business day in the US?"

Tool call: is_business_day(date="2025-07-04", country="US")

{
  "date": "2025-07-04",
  "country": "US",
  "is_business_day": false,
  "is_weekend": false,
  "is_holiday": true,
  "holiday_name": "Independence Day"
}

Today's date in a specific timezone

"What's today's date in New York?"

Tool call: get_current_date(timezone="America/New_York")

{
  "date": "2026-04-23",
  "timezone": "America/New_York",
  "day_of_week": "Thursday",
  "iso_week": 17
}

Next business day

"I'm scheduling a task for July 3, 2025 in the US. What's the next business day after that?"

Tool call: next_business_day(date="2025-07-03", country="US")

{
  "input_date": "2025-07-03",
  "next_business_day": "2025-07-07",
  "country": "US",
  "skipped_days": 4
}

Previous business day

"What was the last business day before July 4, 2025 in the US?"

Tool call: previous_business_day(date="2025-07-04", country="US")

{
  "input_date": "2025-07-04",
  "previous_business_day": "2025-07-03",
  "country": "US",
  "skipped_days": 1
}

Last business day of the month

"When is the last business day of May 2026 in the US?"

Tool call: last_business_day_of_month(year=2026, month=5, country="US")

{
  "year": 2026,
  "month": 5,
  "country": "US",
  "last_business_day": "2026-05-29",
  "last_calendar_day": "2026-05-31"
}

Business days between two dates

"How many business days are between December 20, 2025 and January 5, 2026 in the US?"

Tool call: business_days_between(start_date="2025-12-20", end_date="2026-01-05", country="US")

{
  "start_date": "2025-12-20",
  "end_date": "2026-01-05",
  "country": "US",
  "inclusive": false,
  "business_days": 8,
  "calendar_days": 16,
  "holidays_in_range": [
    { "date": "2025-12-25", "name": "Christmas Day" },
    { "date": "2026-01-01", "name": "New Year's Day" }
  ]
}

List holidays for a year (regional subdivision)

"List the 2026 public holidays in Bavaria, Germany."

Tool call: list_holidays(year=2026, country="DE", subdiv="BY")

{
  "year": 2026,
  "country": "DE",
  "holidays": [
    { "date": "2026-01-01", "name": "New Year's Day" },
    { "date": "2026-01-06", "name": "Epiphany" },
    { "date": "2026-04-03", "name": "Good Friday" },
    { "date": "2026-04-06", "name": "Easter Monday" },
    { "date": "2026-05-01", "name": "Labor Day" },
    { "date": "2026-05-14", "name": "Ascension Day" },
    { "date": "2026-05-25", "name": "Whit Monday" },
    { "date": "2026-06-04", "name": "Corpus Christi" },
    { "date": "2026-10-03", "name": "German Unity Day" },
    { "date": "2026-11-01", "name": "All Saints' Day" },
    { "date": "2026-12-25", "name": "Christmas Day" },
    { "date": "2026-12-26", "name": "Second Day of Christmas" }
  ],
  "subdiv": "BY"
}

Discover supported subdivisions

"Which German states (subdivisions) can I use for holiday lookups?"

Tool call: get_supported_subdivisions(country="DE")

{
  "country": "DE",
  "subdivisions": ["BB","BE","BW","BY","HB","HE","HH","MV","NI","NW","RP","SH","SL","SN","ST","TH","Augsburg"],
  "aliases": {
    "Brandenburg": "BB",
    "Berlin": "BE",
    "Baden-Württemberg": "BW",
    "Bayern": "BY",
    "Bremen": "HB",
    "Hessen": "HE",
    "Hamburg": "HH",
    "Mecklenburg-Vorpommern": "MV",
    "Niedersachsen": "NI",
    "Nordrhein-Westfalen": "NW",
    "Rheinland-Pfalz": "RP",
    "Schleswig-Holstein": "SH",
    "Saarland": "SL",
    "Sachsen": "SN",
    "Sachsen-Anhalt": "ST",
    "Thüringen": "TH"
  }
}

• See get_supported_countries() for the full list of 250+ supported countries and their subdivision codes.

Conventions

• Dates: ISO 8601 strings (YYYY-MM-DD).
• Countries: ISO 3166-1 alpha-2 codes (DE, US, GB, ...) — case-insensitive.
• Timezones: IANA names (Europe/Berlin, America/New_York, ...).
• Subdivisions (optional): country-specific region codes (BY for Bavaria, CA for California, ...). Case-sensitive — pass exactly as returned by get_supported_countries. Omit to get nation-wide holidays only.

Regional subdivisions: all country-aware tools (is_business_day, next_business_day, previous_business_day, last_business_day_of_month, business_days_between, list_holidays) accept an optional subdiv parameter. Example: country="DE", subdiv="BY" treats Epiphany (Jan 6) as a holiday in Bavaria. Discover valid codes via get_supported_countries (returns a subdivisions: list[str] per country; [] for countries without regional variants, e.g. JP). For a single-country lookup that also includes alias names (e.g. "Bavaria" → "BY"), use get_supported_subdivisions(country="DE") — returns {subdivisions: ["BY", ...], aliases: {"Bavaria": "BY", ...}}.

Contributing

Contributions are welcome. See CONTRIBUTING.md for build, test, issue, and pull request guidelines. The project repo is at https://github.com/fbdo/business-day-mcp.

License

This project is licensed under the MIT License. See LICENSE.