bizdays
bizdays is an MCP server that provides verified, deterministic business-day calculations for 206 countries, accounting for country-specific weekend rules and real public holidays. It offers 6 tools:
add_business_days: Calculate a date N working days before or after a start date, skipping the correct weekends and public holidays for a given country.count_business_days: Count working days between two dates (inclusive or exclusive), with a breakdown of weekend days and named holidays skipped.is_business_day: Check whether a specific date is a working day in a given country; if not, get the exact reason (weekend, named public holiday, or custom holiday).next_business_day: Get the first working day strictly after a given date.previous_business_day: Get the most recent working day strictly before a given date.country_rule: Retrieve a country's weekend rules (and their source — CLDR, curated override, or Sat/Sun default), whether a public-holiday calendar is applied, a verified/unverified confidence flag, and any relevant caveats.
All tools support an optional extraHolidays parameter to inject custom non-working dates (e.g., company shutdowns).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bizdaysWhat is 5 business days after Dec 22, 2025 in the UK?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bizdays
Verified business-day math for AI agents — holidays + per-country weekends, not guesses.
Verified, trustworthy data tools for AI agents. "Qiniso" means "truth" in Zulu.
Website · npm · MCP endpoint · MCP Registry
LLMs answer "what date is 5 business days after Dec 22nd in the UK?", "how many working days are in this month?", and "is Friday a working day in Saudi Arabia?" confidently and often wrongly — they miscount, forget public holidays, and assume every country's weekend is Saturday/Sunday. bizdays gives an agent the deterministic answer from real public-holiday calendars and per-country weekend rules, showing the weekend rule and the exact holidays it skipped.
Two things break naive business-day math, and bizdays fixes both: weekends aren't Sat/Sun everywhere (Fri/Sat in Saudi Arabia, Egypt & Israel; Fri in Iran; Sun in India; Sat/Sun in the UAE since 2022), and "holiday" must mean a real day off — off-the-shelf data counts observances like Valentine's Day and Christmas Eve, which are not days off.
Counting the working days in a month, a frontier LLM with no tools is wrong 63% of the time, cold — and 23% across business-day questions overall. bizdays: 0%.
Add it to Claude
Settings → Connectors → Add custom connector, and paste — no login, no key:
https://bizdays.qinisolabs.workers.dev/mcpStateless, reads no user data, requires no secrets. Prefer to run it locally over stdio? Add { "command": "npx", "args": ["-y", "@qinisolabs/bizdays"] } under mcpServers in your client config.
Related MCP server: business-day-mcp
Use it as a library
Every tool is also a typed function — no MCP required:
npm i @qinisolabs/bizdaysimport { addBusinessDays, countBusinessDays, isBusinessDay } from "@qinisolabs/bizdays";
addBusinessDays("2025-12-22", 5, "GB").result; // "2025-12-31" (skips Christmas + Boxing Day)
countBusinessDays("2025-12-01", "2025-12-31", "US"); // { businessDays: 22, ... }
isBusinessDay("2025-06-13", "SA").isBusinessDay; // false — Friday is weekend in Saudi Arabia
isBusinessDay("2025-02-14", "US").isBusinessDay; // true — Valentine's Day is not a public holidayEvery function returns a rich result: the answer, the weekday, exactly which weekends and named holidays were skipped, the weekend rule and its source, and a confidence flag.
What it does — 6 tools
Tool | What it answers |
add_business_days | What date is N working days from a start date? (N may be negative) |
count_business_days | How many working days between two dates? (endpoints inclusive by default) |
is_business_day | Is this date a working day? If not, why (weekend / public holiday with its name)? |
next_business_day | First working day strictly after a date |
previous_business_day | Last working day strictly before a date |
country_rule | The weekend rule + its source, whether holidays apply, and a confidence flag |
Public holidays for 206 countries (and subdivisions) come from date-holidays, filtered to type: "public". Weekends come from Unicode CLDR via the runtime Intl API, plus a curated data/weekend-overrides.json correction layer (e.g. Bangladesh Fri/Sat, Nepal Sat-only) — the maintained data is the moat.
What it is not
Not all-holidays. It counts weekends and public holidays only — not regional or optional observances. Pass company shutdowns or regional days via
extraHolidays.Not uniformly verified. A Tier-1 set of ~65 countries is verified; others work but are flagged
unverified. Where no holiday calendar exists (e.g. Qatar, Kuwait, Oman), the correct weekend still applies and the response says so (holidaysApplied: false).Not a live service dependency. The library makes no network calls; dates are
YYYY-MM-DDin UTC.
Architecture
A single TypeScript package exposing one MCP server over two transports — stdio (local / npx) and a Cloudflare Worker (the hosted edge endpoint) — both driven by the same core.ts tool definitions, which also power the importable library.
npm install
npm run build
npm testPrivacy
This tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. All reference data is bundled — no network calls, and nothing leaves your device. Full policy: https://qinisolabs.github.io/privacy.html.
License
Apache-2.0. Bundled holiday data is from date-holidays (ISC AND CC-BY-3.0); see NOTICE.
Available Tools
6 toolsadd_business_daysA
USE THIS to compute a deadline or settlement date instead of counting on your fingers — never guess what date is N working days away. Adds (or subtracts, if N is negative) business days to a start date, skipping that country's weekends AND its public holidays. Weekends are country-correct (e.g. Friday/Saturday in Saudi Arabia, Saturday/Sunday in the UAE) and only real public holidays are skipped — not observances like Valentine's Day. Returns the result date, its weekday, and exactly which weekends/holidays were skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | Start date, YYYY-MM-DD. | |
| days | Yes | Business days to add; negative subtracts. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. | |
| extraHolidays | No | Optional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully reveals behavior: it handles negative values, adjusts weekends per country (e.g., Friday/Saturday in Saudi Arabia), skips only real public holidays not observances, and returns result date, weekday, and skipped weekends/holidays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with 'USE THIS', and contains no redundant information. Every clause adds meaningful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and four parameters, the description covers all essential aspects: purpose, input parameters, behavior (weekends, holidays, negative days), and output. It is fully adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining country-specific weekend behavior and the distinction between public holidays and observances, which goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool computes deadlines or settlement dates by adding/subtracting business days, using a clear verb and resource. It distinguishes itself from siblings like count_business_days and is_business_day by focusing on date calculation rather than counting or checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description begins with 'USE THIS' to strongly indicate when to use, and provides context about computing deadlines instead of manual counting. However, it does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
count_business_daysA
USE THIS to count working days between two dates instead of estimating — LLMs routinely miscount because they forget holidays or a country's weekend rule. Counts business days from start to end (both endpoints included by default), excluding that country's weekends and public holidays. Returns the count plus a breakdown of weekend days and the named holidays in range.
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | Start date, YYYY-MM-DD. | |
| end | Yes | End date, YYYY-MM-DD. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. | |
| inclusive | No | Include both endpoints (default true); false excludes the start date. | |
| extraHolidays | No | Optional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden of disclosing behavior. It states that both endpoints are included by default (hinting at the inclusive parameter), that weekends and public holidays of the specified country are excluded, and that the output includes a count plus a breakdown of weekend days and named holidays. This is sufficient for a counting tool, though it doesn't specify error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no wasted words. It front-loads the key instruction 'USE THIS', making it immediately clear. Every sentence adds value: the first explains why the tool is needed, and the second explains what it does and returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, all described in the schema. There is no output schema, but the description mentions the return value (count plus breakdown). Given the complexity of a date-counting tool, the description provides enough context for an agent to understand input, behavior, and output. It could be more complete by noting edge cases like invalid dates, but it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already described in the schema. The description adds minimal additional meaning: it mentions the default inclusive behavior of both endpoints, which aligns with the inclusive parameter. This slight addition justifies a score slightly above baseline (3), as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool counts working days between two dates, accounting for holidays and weekends of a specific country. The description uses a specific verb 'count' and resource 'business days', and the name itself distinguishes it from sibling tools like add_business_days, is_business_day, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this tool for counting working days instead of estimating, noting that LLMs commonly miscount due to holidays or weekend rules. It implies the tool is accurate but does not explicitly mention when not to use it or contrast with siblings beyond the name. Still, it provides clear context for its primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
country_ruleA
USE THIS to see how bizdays treats a country before relying on a result — it returns the weekend days (with their source: a Qiniso override, CLDR, or the Sat/Sun default), whether a public-holiday calendar is applied, a confidence flag (verified vs unverified), and any caveats. Call this when a country looks unusual (Gulf states, Israel, Nepal) or when a result is surprising.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully shoulders the burden. It discloses all key outputs (weekend day sources, calendar application, confidence, caveats) and implies read-only behavior. Missing are potential errors or auth requirements, but for a simple lookup, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first lists what it returns, second gives usage advice. Front-loaded with 'USE THIS', no redundant words. Highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description is comprehensive. It covers what the tool does, what it returns, and when to use it. No gaps for an agent to make a correct decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the 'country' parameter (ISO 3166-1 alpha-2, examples). The description adds no additional parameter semantics beyond usage examples, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool inspects how bizdays treats a country, listing specific outputs (weekend days, sources, public holiday calendar, confidence flag, caveats). This distinguishes it from sibling tools that modify or calculate business days, so an agent can easily differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this tool 'before relying on a result' and when a country is unusual (Gulf states, Israel, Nepal) or results are surprising. This provides clear when-to-use and implies when not to use, making it highly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
is_business_dayA
USE THIS to check whether a specific date is a working day before scheduling on it — do not assume any weekday is open. Returns whether the date is a business day in the given country and, if not, the precise reason (weekend, public holiday with its name, or a custom holiday). Country-correct weekends and public-holidays-only.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date, YYYY-MM-DD. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. | |
| extraHolidays | No | Optional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns whether it's a business day and the precise reason if not (weekend, public holiday, custom holiday). It mentions 'Country-correct weekends and public-holidays-only' which explains logic. No destructive or extra behaviors need disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are concise and front-loaded with 'USE THIS'. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but description hints at return value (business day status and reason). Also explains country-specific weekends and holidays. It is complete for a simple check tool with 100% parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the schema already describes all parameters with types, descriptions, and requirements. The description adds no additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if a date is a working day before scheduling, and specifies it returns business day status with reasons. This distinguishes it from siblings like add_business_days or next_business_day which manipulate dates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'USE THIS to check whether a specific date is a working day before scheduling on it — do not assume any weekday is open.' This gives clear when-to-use guidance. Alternatives are implied by sibling names but not explicitly listed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
next_business_dayA
USE THIS to find the next working day after a date (e.g. when something falls due on a weekend or holiday) instead of guessing. Returns the first business day strictly after the given date for that country.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date, YYYY-MM-DD. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. | |
| extraHolidays | No | Optional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses that the result is the first business day strictly after the given date, taking into account the country and optional extra holidays. It does not mention error cases or performance, but provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence is an imperative directive, and the second explains the output. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return value (first business day strictly after). It covers the parameters indirectly. It could mention error handling or edge cases, but for a simple tool, the completeness is satisfactory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reinforces the purpose but adds no new semantic detail beyond the schema, such as clarifying the 'extraHolidays' parameter or specifying date format beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: find the next working day after a date, using a specific verb and resource. It distinguishes from siblings by emphasizing 'strictly after' and providing an example scenario, differentiating it from previous_business_day and add_business_days.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an implicit usage guideline ('USE THIS... instead of guessing') and an example scenario, but it does not explicitly exclude alternatives or contrast with sibling tools. More explicit guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
previous_business_dayA
USE THIS to find the most recent working day before a date (e.g. the last open day before a holiday) instead of guessing. Returns the first business day strictly before the given date for that country.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date, YYYY-MM-DD. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA. | |
| extraHolidays | No | Optional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It clearly states the return value ('first business day strictly before the given date for that country') and notes the effect of extraHolidays. However, it does not disclose any read-only nature or potential rate limits, which is acceptable for a simple lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'USE THIS', zero waste. Every word is necessary and contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains what the tool returns. All parameters are described in schema, and the description covers the core behavior. For a simple utility tool, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning to 'extraHolidays' by providing an example ('e.g. a company shutdown day'). It does not add much to 'date' or 'country' beyond the schema, but the overall desc adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb-resource pair ('find the most recent working day') and distinguishes from siblings like 'next_business_day' by focusing on the 'previous' direction. The phrase 'USE THIS to find... instead of guessing' clarifies its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (before a date/holiday) and provides an alternative ('instead of guessing'), but it does not explicitly exclude other tools like 'next_business_day' or 'is_business_day'. For a straightforward tool, this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v1.0.0- First observed
add_business_days - First observed
count_business_days - First observed
country_rule - First observed
is_business_day - First observed
next_business_day - First observed
previous_business_day
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: adding/subtracting days, counting between dates, checking holiday rules, verifying a single date, and finding next/previous business days. No overlap exists.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_business_days, is_business_day, next_business_day). 'country_rule' is the only slight deviation but still fits the overall style.
With 6 tools, the server covers all essential business day operations without unnecessary tools. The count is well-scoped for its purpose.
The tool set provides complete CRUD-like operations for business days: addition, subtraction, counting, checking, and finding adjacent days. The inclusion of country_rule adds transparency. No obvious gaps.
Maintenance
Related MCP Connectors
Reliable Australian business-day, public-holiday and deadline tools for AI agents.
Public holiday data for 30+ countries. Check holidays, working days and calendars via AI assistants.
Deterministic time tools for AI agents: timezone conversion, business-day math, cron interpretation.
Deterministic date arithmetic with auditable receipts: business days, due dates, holidays.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenancePublic holiday data for 30+ countries. Check holidays, working days, and full calendars via AI assistants like Claude and Cursor.MIT
- AlicenseAqualityCmaintenanceMCP server for business-day arithmetic with country-aware holiday calendars. It offers tools to check, calculate, and list business days and holidays for over 60 countries.9MIT

Qinisoofficial
AlicenseAqualityCmaintenanceThe deterministic fact-verification layer for AI agents. Validates the structured facts an agent emits — IBANs, payment cards, VAT and national tax IDs, crypto and bank addresses, domains, emails, phone numbers, securities and academic identifiers, plus dates, currencies and holidays — against checksums and curated authoritative data, not guesses.561Apache 2.0- AlicenseNot gradedqualityCmaintenanceEnables Japanese business calendar operations such as holiday checking, business day calculations, payment date calculation, fiscal year determination, and deadline tracking, all locally without external API.MIT