# mcp-jp-calendar

[![npm version](https://img.shields.io/npm/v/mcp-jp-calendar.svg)](https://www.npmjs.com/package/mcp-jp-calendar)
[![license](https://img.shields.io/npm/l/mcp-jp-calendar.svg)](LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-6f42c1)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.skypier-jp-works/mcp-jp-calendar)

[日本語版はこちら (Japanese README)](README.ja.md)

**Give your AI agent correct answers about Japanese business days.** An [MCP](https://modelcontextprotocol.io) 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](#why-this-exists)
- [Install](#install)
- [Tools](#tools)
- [Supported range & data source](#supported-range--data-source)
- [The `meta` field](#the-meta-field)
- [Versioning policy](#versioning-policy)
- [Maintenance policy](#maintenance-policy)
- [Disclaimer](#disclaimer)
- [Development](#development)
- [Related tools](#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`

```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:

```bash
npx mcp-jp-calendar
```

Or install it globally:

```bash
npm install -g mcp-jp-calendar
```

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

[MCP Bundles](https://github.com/modelcontextprotocol/mcpb) let you install a local MCP server with a single double-click, no terminal required. Build one from source:

```bash
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:

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

**`add_business_days`** — 1 business day after a Friday:

```jsonc
// 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:

```jsonc
// 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:

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

**`month_end_info`** — month-end falls on a Sunday:

```jsonc
// 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:

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

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

```jsonc
// 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](#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:

```jsonc
"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](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:

```bash
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:

```json
{
  "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

Other MCP servers by the same author:

- [mcp-jp-paid-leave](https://github.com/skypier-jp-works/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)
- [mcp-jp-corporate-id](https://github.com/skypier-jp-works/mcp-jp-corporate-id) — validates and normalizes Japanese corporate numbers and qualified invoice registration numbers

## License

[MIT](LICENSE)