Purpose
bizdays is designed to provide AI agents with verified business-day math capabilities. When answering questions such as "What is the date 5 business days after December 22 in the UK?", "How many business days are in this month?", or "Is Friday a business day in Saudi Arabia?", large language models are often confidently wrong - they miscalculate, forget public holidays, and assume that weekends are Saturday and Sunday in every country. bizdays gives agents deterministic answers using real public holiday calendars and country-specific weekend rules, and shows the weekend rules used and the specific holidays skipped.
Main Capabilities
bizdays provides 6 tools covering the following functions:
- Business day addition and subtraction: add or subtract a number of business days from a specified date.
- Business day counting: count the number of business days in a month or within a date range.
- Find the next business day: find the next business day according to country rules.
- Determine whether a day is a business day: determine this by combining weekend rules and public holidays.
Each function returns rich results: the answer, the day of the week, skipped weekends and named holidays, the weekend rule and its source, and a confidence flag.
For data sources, public holidays for 206 countries (and administrative regions) come from date-holidays and are filtered to type: "public". Weekend rules come from Unicode CLDR (via the runtime Intl API), supplemented by a manually maintained data/weekend-overrides.json correction layer (for example, Bangladesh is Friday/Saturday, Nepal is Saturday only).
How to Use
Connect to Claude
In Claude, go to Settings -> Connectors -> Add custom connector and paste the MCP endpoint - no login and no key required. The service is stateless, does not read user data, and does not require any secrets.
Run Locally
If you prefer to run locally via stdio, add the following under mcpServers in the client configuration:
{ "command": "npx", "args": ["-y", "@qinisolabs/bizdays"] }
Use as a Library
Each tool is also a typed function and can be called without MCP.
Use Cases
- AI agents need to accurately answer questions involving business days, public holidays, and weekend rules.
- In cross-border business scenarios, dates need to be calculated according to the weekend and holiday rules of a specific country.
- Developers integrate business day calculation functionality into applications, avoiding the need to maintain holiday data themselves.
Limitations
- Not all holidays are included: only weekends and public holidays are calculated; regional or optional observance days are not included. Company closure days or regional holidays can be passed in via extraHolidays.
- Not all are verified: about 65 countries belong to the Tier-1 verified set; other countries are usable but are marked as unverified. For countries without a holiday calendar (such as Qatar, Kuwait, and Oman), the correct weekend rules are still applied, and this is stated in the response (holidaysApplied: false).
- Not a real-time service dependency: the library does not make network calls; dates are in UTC YYYY-MM-DD format.
Technical Architecture
A single TypeScript package exposes one MCP server through two transports: stdio (local / npx) and Cloudflare Worker (hosted edge endpoint). Both are driven by the same core.ts tool definitions, which also support the importable library.
Privacy and License
The tool runs locally and does not collect, store, or transmit user data - no analytics, no telemetry, no account. All reference data is bundled, no network calls are made, and data does not leave the device. The full policy is at https://qinisolabs.github.io/privacy.html。
Licensed under Apache-2.0. Bundled holiday data comes from date-holidays (ISC AND CC-BY-3.0); see NOTICE for details.
