business-days-mcp

An MCP server for the date arithmetic that support, billing and operations teams actually do: is this a working day, when is this SLA due, what is the next working day after a bank holiday — plus cron and recurrence-rule parsing for the recurring side of the same job.

It runs offline. No network calls, no stored data, no model calls — every answer is computed from bundled public-holiday rules.

What it does

Business days and SLAs — holiday-aware for ~150 countries and their subdivisions (England and Scotland differ; so do US states), via the holidays package.

Tool	Answers
is_business_day	Is this a working day? If not, is it a weekend or a named holiday?
next_business_day / previous_business_day	The next/last working day around a date
add_business_days	Move ±N working days from a date
business_days_between	How many working days between two dates (half-open)
first_business_day_of_month / last_business_day_of_month	Month boundaries
sla_due_time	When does an N-business-hour SLA fall due, counting only open hours?

Cron and recurrence — parsing only. Nothing is scheduled, stored, or executed; there are no timers and no job store. If you want something run on a schedule, this is deliberately not that tool.

Tool	Answers
validate_cron_expression / explain_cron_expression	Is this cron valid, and what does it mean in English?
next_cron_occurrences	When would it next fire?
validate_recurrence_rule / explain_recurrence_rule	Same, for an RFC 5545 RRULE
next_recurrence_occurrences	Expand an RRULE to its next occurrences

Install and run

The hosted endpoint needs no install at all — see Client configuration. To run it yourself, uvx fetches and runs it:

uvx --from git+https://github.com/Vessark/business-days-mcp business-days-mcp

From a clone:

git clone https://github.com/Vessark/business-days-mcp
cd business-days-mcp
uv sync && uv run business-days-mcp
uv run pytest                         # the tests are the documentation

Client configuration

Hosted — nothing to install

The quickest way in. The same tools, no install, no credentials:

{
  "mcpServers": {
    "vessark": {
      "url": "https://vessark.com/mcp"
    }
  }
}

Run it yourself

If you would rather not depend on someone else's uptime, run it locally — it is the same code, and it never touches the network:

{
  "mcpServers": {
    "business-days": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vessark/business-days-mcp",
        "business-days-mcp"
      ]
    }
  }
}

Examples

// is_business_day — 2026-12-28, UK
{"date": "2026-12-28", "country": "GB"}
→ {"is_business_day": false, "reason": "holiday: Boxing Day (substitute day)"}

// sla_due_time — 8 business hours from Monday 16:00
{"start": "2026-07-27T16:00", "business_hours": 8}
→ {"due": "2026-07-28T16:00:00", "started_within_business_hours": true}

// explain_cron_expression
{"expression": "30 9 * * MON-FRI"}
→ {"explanation": "At 09:30, on Monday through Friday."}

Design notes

Every tool is a pure function of its arguments, which is why the test suite is mostly tables. Invalid input is an ordinary typed result, never an exception — a model that gets an argument wrong gets a readable reason and can correct itself. Every loop that a caller can influence is bounded, so no request can buy an expensive computation. Error messages never echo what you sent, so the server can't be used to relay text into someone else's agent.

Known limits, stated rather than hidden: a working week is Monday–Friday, so countries with Sunday–Thursday weeks are wrong under this assumption; holiday data covers only the years the underlying dataset knows about, and a date outside that range is refused rather than silently answered as an ordinary working day.

Prior art

fbdo/business-day-mcp covers business-day and holiday arithmetic and predates this server. If that is all you need, use it — it also exposes timezone-aware "today" and holiday listing, which this server does not.

This one was built for a different centre of gravity: SLA clocks that count only business hours, and cron / RRULE parsing for the recurring side of the same work. The overlap in the business-day tools is real and the names are conventional; both servers are MIT licensed and both build on the excellent holidays package.

Releasing

Bump the version in both pyproject.toml and server.json, then push a matching tag:

git tag v0.2.0 && git push origin v0.2.0

That runs the test suite, checks the tag agrees with both version fields, and republishes to the MCP registry. Authentication is GitHub OIDC, so no token is stored anywhere.

About

Built and maintained by Vessark. The tools in this repository are the free tier and are open source under the MIT licence. Vessark's workspace tools — the ones that operate on a connected workspace — are the commercial product and are not open source.

Issues and pull requests welcome.