mcp-jp-calendar

mcp-jp-calendar

日本語版はこちら (Japanese README)

Give your AI agent correct answers about Japanese business days. An MCP server that tells Claude (or any MCP client) whether a date is a working day in Japan, what date payment is actually due, and which fiscal quarter you're in — accounting for national holidays, substitute holidays, and conventions no simple weekday check gets right. No API keys, no network calls: all holiday data (2020–2030) is embedded in the package.

Contents

• Why this exists
• Install
• Tools
• Supported range & data source
• The meta field
• Versioning policy
• Maintenance policy
• Disclaimer
• Development
• Related tools

Why this exists

A naive "is it a weekday" check gets Japanese business dates wrong more often than you'd expect. A few real examples this server handles correctly:

Situation	Naive weekday check	What actually happens
Substitute holiday (振替休日)	Children's Day, May 5 2026, falls on a Sunday → looks like the next day (Mon May 6) is a normal business day	May 6 2026 is also a public holiday — Japanese law shifts the holiday to the next non-holiday day
Citizens' holiday (国民の休日)	Sep 22 2026 is a Tuesday, sandwiched between two holidays → looks like a business day	It's a holiday too: when a weekday falls between two national holidays, it automatically becomes one
Gotobi settlement days (五十日)	Japanese invoices and payments conventionally settle on the 5th/10th/15th/20th/25th/month-end — irrelevant in most other countries	next_gotobi finds the next one and, if it lands on a holiday, tells you the actual (pushed-back) business day payment will clear
Fiscal year (年度)	December looks like Q4 if you assume a January-start year	Most Japanese companies run an April–March fiscal year, so December is actually Q3

Get any of these wrong in a scheduling or invoicing agent and you'll pick a bank holiday as a due date, or misreport a quarter. This server encodes the actual rules so your agent doesn't have to guess.

Install

Option 1 — npx (recommended)

No install step required. Add this to your Claude Desktop config (claude_desktop_config.json):

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jp-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-jp-calendar"]
    }
  }
}

Restart Claude Desktop and the tools become available. You can also run it directly:

npx mcp-jp-calendar

Or install it globally:

npm install -g mcp-jp-calendar

Option 2 — .mcpb bundle (one-click install for Claude Desktop)

MCP Bundles let you install a local MCP server with a single double-click, no terminal required. Build one from source:

git clone https://github.com/skypier-jp-works/mcp-jp-calendar.git
cd mcp-jp-calendar
npm install
npm run build
mkdir -p mcpb-dist/server && cp build/*.js mcpb-dist/server/
cd mcpb-dist
npm install --omit=dev
npm install -g @anthropic-ai/mcpb
mcpb pack . mcp-jp-calendar.mcpb

Then double-click the resulting mcp-jp-calendar.mcpb file to install it in Claude for macOS/Windows.

Tools

All dates are given and returned in YYYY-MM-DD format (e.g. 2026-08-15). month_end_info takes a YYYY-MM month string (e.g. 2026-08).

Tool	Description
is_business_day	Check whether a given date is a business day
add_business_days	Get the date N business days after/before a given date
count_business_days	Count business days between two dates (inclusive)
next_gotobi	Get the next "gotobi" settlement day (5th, 10th, 15th, 20th, 25th, or last day of month), plus the actual business day if that date is a holiday
month_end_info	Get the last day of a given month, and the effective closing date if that day is a holiday
fiscal_period	Determine which fiscal year and quarter a date falls in (fiscal year start month is configurable; defaults to April)
list_holidays	List Japan's national holidays for a given year

All of is_business_day, add_business_days, count_business_days, next_gotobi, and month_end_info accept two optional parameters:

• weekendDays: array of weekday numbers to treat as non-working days. 0=Sun … 6=Sat. Defaults to [0, 6].
• customHolidays: array of YYYY-MM-DD strings for company-specific closures (e.g. a year-end shutdown).

Examples

is_business_day — a Saturday:

// Request: { "date": "2026-08-15" }
{ "date": "2026-08-15", "isBusinessDay": false, "reason": "土曜日" }

add_business_days — 1 business day after a Friday:

// Request: { "date": "2026-07-24", "businessDays": 1 }
{ "startDate": "2026-07-24", "businessDays": 1, "resultDate": "2026-07-27" }

count_business_days — a full Mon–Sun week:

// Request: { "startDate": "2026-07-27", "endDate": "2026-08-02" }
{ "startDate": "2026-07-27", "endDate": "2026-08-02", "businessDays": 5 }

next_gotobi — the 15th falls on a Saturday, so it's pushed back:

// Request: { "date": "2026-08-11" }
{ "gotobiDate": "2026-08-15", "isBusinessDay": false, "actualDate": "2026-08-14" }

month_end_info — month-end falls on a Sunday:

// Request: { "yearMonth": "2027-01" }
{ "yearMonth": "2027-01", "monthEndDate": "2027-01-31", "isBusinessDay": false, "actualClosingDate": "2027-01-29" }

fiscal_period — December, under Japan's standard April-start fiscal year:

// Request: { "date": "2026-12-01" }
{ "date": "2026-12-01", "fiscalYearStartMonth": 4, "fiscalYear": 2026, "quarter": 3 }

list_holidays — excerpt showing a citizens' holiday (国民の休日):

// Request: { "year": 2026 }
{
  "year": 2026,
  "holidays": [
    { "date": "2026-09-21", "name": "敬老の日" },
    { "date": "2026-09-22", "name": "国民の休日" },
    { "date": "2026-09-23", "name": "秋分の日" }
  ]
}

(Examples above are abbreviated for readability — every response also includes a meta field; see The meta field.)

Supported range & data source

Only dates from 2020 to 2030 are supported. Dates outside this range return an error.

• Holiday data for 2020–2027 is confirmed, sourced directly from Japan's Cabinet Office (内閣府) official holiday CSV: https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html
• Holiday data for 2028–2030 is a computed estimate: the vernal/autumnal equinox holidays (春分の日 / 秋分の日) aren't officially announced that far ahead, so they're calculated with the standard astronomical approximation formula and may differ from the eventual official announcement by up to a day.
• The 2020/2021 Tokyo Olympics special holiday moves (Marine Day, Sports Day, Mountain Day) are included.
• Substitute holidays (振替休日) and citizens' holidays (国民の休日) are computed automatically and have been cross-checked against the official Cabinet Office data for 2020–2027.

The meta field

Every tool response includes a meta block alongside the actual result:

"meta": {
  "dataVerifiedOn": "2026-07-28",
  "sources": [{ "label": "Cabinet Office official holiday CSV", "url": "https://..." }],
  "staleWarning": null
}

• dataVerifiedOn: the date this server's holiday data was last checked against the primary source.
• sources: the source(s) backing this response (fiscal_period doesn't use holiday data at all, so its sources is an empty array).
• staleWarning: a bilingual (Japanese/English) warning when more than 6 months have passed since dataVerifiedOn; null otherwise.

Dates outside the supported range (2020–2030) still return a hard error rather than a warning, since no data exists for those dates at all.

Versioning policy

• Any update to the embedded holiday data bumps the minor version (e.g. 1.1.0 → 1.2.0). Patch versions are reserved for bug fixes and documentation.
• Changes are recorded in CHANGELOG.md, noting when and what was updated.

Maintenance policy

• The maintainer intends to update src/holidays.ts whenever the Public Holiday Act is amended or the Cabinet Office publishes updated data. Since this server never makes network calls at runtime, reflecting a change requires a manual update.
• If you're aware of a holiday change (new/moved/removed holiday), please report it via GitHub Issues: https://github.com/skypier-jp-works/mcp-jp-calendar/issues
• For anything important, check meta.dataVerifiedOn and meta.staleWarning, and confirm against the latest Cabinet Office announcement if needed.

Disclaimer

• The accuracy of this tool's calculations is not guaranteed.
• Actual business days and closing dates are governed by each company's own work rules and by agreements with business partners, which always take precedence over this tool's output.
• If you are using this tool for any important business decision, you must independently verify the results yourself.

Development

Clone and build from source if you want to modify the server:

git clone https://github.com/skypier-jp-works/mcp-jp-calendar.git
cd mcp-jp-calendar
npm install
npm run build   # compiles src/ -> build/
npm test        # 38 tests covering all 7 tools

Claude Desktop config for a locally built copy:

{
  "mcpServers": {
    "jp-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jp-calendar/build/index.js"]
    }
  }
}

Project structure

mcp-jp-calendar/
├── src/
│   ├── holidays.ts    # Embedded holiday data for 2020-2030 (Cabinet Office data + estimates)
│   ├── dataMeta.ts    # Data-verification date, sources, and staleness-warning helpers
│   ├── dateUtils.ts   # Core logic: business days, closing dates, fiscal periods, etc.
│   └── index.ts       # MCP server entry point (exposes the 7 tools)
├── tests/
│   ├── dateUtils.test.ts
│   └── dataMeta.test.ts
├── mcpb-dist/
│   └── manifest.json  # MCP Bundle (.mcpb) manifest — see Install, Option 2
├── package.json
├── tsconfig.json
├── CHANGELOG.md       # Record of holiday-data updates and spec changes
├── LICENSE
├── README.md          # this file
└── README.ja.md       # Japanese version

If a holiday law changes, this server's embedded data will not update automatically — src/holidays.ts needs to be updated manually.

Related tools

Another MCP server by the same author:

• mcp-jp-paid-leave — calculates Japanese statutory annual paid leave (entitlement grants, attendance-rate checks, proportional grants, carryover, the 5-day mandatory-use rule, and more)

License

MIT