mcp-jp-calendar

mcp-jp-calendar

日语版请见此处 (Japanese README)

让你的 AI Agent 正确回答有关日本工作日的问题。 一个 MCP 服务，可告知 Claude（或任何 MCP 客户端）某个日期在日本是否为工作日、实际付款到期日是哪一天，以及当前处于哪个财季——并考虑法定节假日、补休日，以及简单判断星期几无法正确处理的惯例。无需 API 密钥，也不进行网络调用：所有节假日数据（2020–2030）都内置于程序包中。

目录

• 存在的理由
• 安装
• 工具
• 支持范围与数据来源
• meta 字段
• 版本策略
• 维护策略
• 免责声明
• 开发
• 相关工具

存在的理由

简单地判断“是不是工作日”，经常会把日本的工作日期弄错，程度超乎你的预料。以下是此服务能够正确处理的几个实际例子：

情况	简单的星期几判断	实际情况
补休日（振替休日）	2026 年 5 月 5 日儿童节恰逢星期日 → 看起来次日（5 月 6 日，星期一）是普通工作日	2026 年 5 月 6 日也是法定节假日——日本法律规定，节假日顺延至下一个非节假日
国民节假日（国民の休日）	2026 年 9 月 22 日是星期二，夹在两个节假日之间 → 看起来是工作日	这天也是节假日：当一个工作日处于两个法定节假日之间时，会自动成为节假日
五十日结算日（五十日）	日本的发票和付款通常在每月 5 日、10 日、15 日、20 日、25 日和月末结算——这在大多数其他国家并不常见	next_gotobi 会找到下一个结算日；若结算日恰逢节假日，还会告知你款项实际结算的顺延工作日
财年（年度）	如果你假设财年从 1 月开始，那么 12 月看起来就像 Q4	日本的大多数公司采用 4 月至次年 3 月的财年，因此 12 月实际上是 Q3

如果调度或开票 Agent 把这些情况弄错，就可能把银行假日定为到期日，或报告错误的季度。此服务将实际规则编码其中，让你的 Agent 无需猜测。

安装

选项 1 — npx（推荐）

无需安装。将以下内容添加到你的 Claude Desktop 配置文件（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"]
    }
  }
}

重启 Claude Desktop 后即可使用这些工具。你也可以直接运行：

npx mcp-jp-calendar

或者全局安装：

npm install -g mcp-jp-calendar

选项 2 — .mcpb 捆绑包（Claude Desktop 一键安装）

MCP Bundles 支持通过双击一次安装本地 MCP 服务，无需使用终端。可从源代码构建：

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

然后双击生成的 mcp-jp-calendar.mcpb 文件，即可在 macOS/Windows 版 Claude 中安装。

工具

所有日期均以 YYYY-MM-DD 格式提供和返回（例如 2026-08-15）。month_end_info 接受 YYYY-MM 格式的月份字符串（例如 2026-08）。

工具	描述
is_business_day	检查给定日期是否为工作日
add_business_days	获取给定日期之前或之后 N 个工作日的日期
count_business_days	计算两个日期之间（含首尾）的工作日数量
next_gotobi	获取下一个“五十日”结算日（5 日、10 日、15 日、20 日、25 日或月末），如果该日期是假日，还会返回实际工作日
month_end_info	获取给定月份的最后一天，以及如果该日是假日则调整后的结算日期
fiscal_period	确定某个日期所属的财年和季度（可配置财年起始月份，默认为 4 月）
list_holidays	列出指定年份的日本国定假日

is_business_day、add_business_days、count_business_days、next_gotobi 和 month_end_info 均接受两个可选参数：

• weekendDays：要视为非工作日的星期编号数组。0=周日 … 6=周六。默认值为 [0, 6]。
• customHolidays：公司特定休假日的 YYYY-MM-DD 字符串数组（例如年末停业日）。

示例

is_business_day — 某个星期六：

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

add_business_days — 星期五之后 1 个工作日：

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

count_business_days — 完整的周一至周日一周：

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

next_gotobi — 15 日是星期六，因此结算日顺延：

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

month_end_info — 月末是星期日：

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

fiscal_period — 在日本标准的 4 月起始财年中，某个 12 月日期：

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

list_holidays — 展示国民の休日的摘录：

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

（以上示例为便于阅读而有所删节——每个响应还包含一个 meta 字段；请参阅meta 字段。）

支持范围与数据源

仅支持 2020 年至 2030 年 的日期。超出此范围的日期会返回错误。

• 2020–2027 年的假日数据已确认，直接来源于日本内阁府官方假日 CSV：https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html
• 2028–2030 年的假日数据为计算估算值：春分和秋分假日（春分の日 / 秋分の日）不会提前这么久正式公布，因此使用标准天文近似公式计算，结果可能与最终官方公告相差最多一天。
• 已纳入 2020/2021 年东京奥运会期间的特别假日调整（海之日、体育之日、山之日）。
• 系统会自动计算补休日（振替休日）和国民の休日，并已与内阁府 2020–2027 年的官方数据交叉核验。

meta 字段

每个工具响应都会在实际结果旁包含一个 meta 块：

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

• dataVerifiedOn：上次根据主要来源核验此服务假日数据的日期。
• sources：支撑此响应的数据来源（fiscal_period 完全不使用假日数据，因此其 sources 是一个空数组）。
• staleWarning：自 dataVerifiedOn 起超过 6 个月时显示的日英双语警告；否则为 null。

超出支持范围（2020–2030）的日期仍会返回硬错误，而不是警告，因为这些日期完全没有数据。

版本管理策略

• 嵌入的假日数据每次更新都会提升次版本号（例如 1.1.0 → 1.2.0）。修订版本号仅用于错误修复和文档更新。
• 更新内容会记录在 CHANGELOG.md 中，注明更新的时间和内容。

维护政策

• 维护者计划在《公共假日法》修订或内阁府发布更新数据时更新 src/holidays.ts。由于此服务在运行时不会发起网络请求，要反映变更，必须手动更新。
• 如果你发现假日变更（新增、调整或取消），请通过 GitHub Issues 报告： https://github.com/skypier-jp-works/mcp-jp-calendar/issues
• 如需核实重要信息，请查看 meta.dataVerifiedOn 和 meta.staleWarning，并在需要时对照内阁府的最新公告确认。

免责声明

• 本工具的计算结果不保证准确。
• 实际工作日和休业日由各公司的工作规则及与业务合作伙伴达成的协议决定，且始终以这些规定为准，而非本工具的输出。
• 如果你要将本工具用于任何重要的业务决策，必须自行独立核实结果。

开发

如果你想修改此服务，可以克隆源代码并进行构建：

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 配置：

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

项目结构

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

如果假日相关法律发生变化，此服务内嵌的数据不会自动更新——需要手动更新 src/holidays.ts。

相关工具

同一作者开发的其他 MCP 服务：

• mcp-jp-paid-leave — 计算日本法定年假（授予天数、出勤率检查、按比例授予、结转、5 天强制使用规则等）
• mcp-jp-corporate-id — 验证并规范化日本法人编号和合格发票注册编号

许可证

MIT